LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
curl --location --request PUT "$LAGO_URL/api/v1/subscriptions/:id" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"subscription": {
"name": "Repository B",
"ending_at": "2022-10-08T00:00:00Z",
"subscription_at": "2022-08-08T00:00:00Z",
"plan_overrides": {
"amount_cents": 10000,
"amount_currency": "USD",
"description": "Plan for early stage startups.",
"invoice_display_name": "Startup plan",
"name": "Startup",
"tax_codes": [
"french_standard_vat"
],
"trial_period": 5,
"charges": [
{
"id": "cha_12345",
"billable_metric_id": "bm_12345",
"invoice_display_name": "Setup",
"min_amount_cents": 0,
"tax_codes": [
"standard_vat"
],
"properties": {
"graduated_ranges": [
{
"from_value": 0,
"to_value": 10,
"flat_amount": "10",
"per_unit_amount": "0.5"
}
]
}
},
{
"id": "cha_67890",
"billable_metric_id": "bm_67890",
"invoice_display_name": "FX Transfer",
"min_amount_cents": 0,
"properties": {
"graduated_percentage_ranges": [
{
"from_value": 0,
"to_value": 10,
"rate": "1",
"flat_amount": "10"
}
]
}
},
{
"id": "cha_111213",
"billable_metric_id": "bm_111213",
"invoice_display_name": "API calls",
"min_amount_cents": 0,
"properties": {
"amount": "30",
"free_units": 100,
"package_size": 1000
}
},
{
"id": "cha_141516",
"billable_metric_id": "bm_141516",
"invoice_display_name": "Interchange",
"min_amount_cents": 0,
"properties": {
"rate": "1",
"fixed_amount": "0.5",
"free_units_per_events": 5,
"free_units_per_total_aggregation": "500",
"per_transaction_max_amount": "3.75",
"per_transaction_min_amount": "1.75"
}
},
{
"id": "cha_171819",
"billable_metric_id": "bm_171819",
"invoice_display_name": "Seats",
"min_amount_cents": 0,
"properties": {
"volume_ranges": [
{
"from_value": 0,
"to_value": 10,
"flat_amount": "10",
"per_unit_amount": "0.5"
}
]
}
},
{
"id": "cha_202122",
"billable_metric_id": "bm_202122",
"invoice_display_name": "Interchange",
"min_amount_cents": 0,
"filters": [
{
"values": {
"cloud": ["aws"],
"region": ["us-east-1"]
},
"properties": {
"graduated_ranges": [
{
"from_value": 0,
"to_value": 10,
"flat_amount": "10",
"per_unit_amount": "0.5"
}
]
}
}
]
}
]
}
}
}'
from lago_python_client.client import Client
from lago_python_client.exceptions import LagoApiError
from lago_python_client.models import Subscription
client = Client(api_key='__YOUR_API_KEY__')
update_params = Subscription(name='new name', subscription_at='2022-08-08T00:00:00Z', ending_at= '2023-08-08T00:00:00Z')
try:
client.subscriptions.update(update_params, 'id')
except LagoApiError as e:
repair_broken_state(e) # do something on error or raise your own exception
require 'lago-ruby-client'
client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')
update_params = { name: 'new name', subscription_at: '2022-08-08T00:00:00Z', ending_at: '2022-08-08T00:00:00Z' }
client.subscriptions.update(update_params, 'id')
await client.subscriptions.updateSubscription("external_id", {
subscription: {
name: "new name",
subscription_at: "2022-08-08T00:00:00Z",
ending_at: "2023-08-08T00:00:00Z",
},
});
{
"subscription": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"billing_time": "anniversary",
"name": "Repository A",
"plan_code": "premium",
"plan_amount_cents": 10000,
"plan_amount_currency": "USD",
"status": "active",
"created_at": "2022-08-08T00:00:00Z",
"canceled_at": "2022-09-14T16:35:31Z",
"started_at": "2022-08-08T00:00:00Z",
"ending_at": "2022-10-08T00:00:00Z",
"subscription_at": "2022-08-08T00:00:00Z",
"terminated_at": "2022-09-14T16:35:31Z",
"previous_plan_code": null,
"next_plan_code": null,
"downgrade_plan_date": "2022-04-30",
"trial_ended_at": "2022-08-08T00:00:00Z",
"current_billing_period_started_at": "2022-08-08T00:00:00Z",
"current_billing_period_ending_at": "2022-09-08T00:00:00Z",
"on_termination_credit_note": "credit",
"on_termination_invoice": "generate",
"payment_method": {
"payment_method_type": "provider",
"payment_method_id": "1a901a90-1a90-1a90-1a90-1a901a901a90"
},
"consolidate_invoice": true,
"progressive_billing_disabled": false,
"cancellation_reason": "payment_failed",
"activated_at": "2022-08-08T00:00:00Z",
"activation_rules": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"type": "payment",
"timeout_hours": 48,
"status": "pending",
"expires_at": "2022-08-10T00:00:00Z",
"created_at": "2022-08-08T00:00:00Z",
"updated_at": "2022-08-08T00:00:00Z"
}
],
"purchase_order_number": "PO-123",
"billing_entity_code": "default",
"applied_invoice_custom_sections": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"created_at": "2023-07-06T14:35:58Z",
"invoice_custom_section": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "EU Bank Details",
"code": "eu_bank_details",
"description": "This section contains the bank details for EU customers.",
"details": "Bank Name: Lago Bank, IBAN: FR7630004000031234567890143",
"display_name": "Bank Details:",
"applied_to_organization": true,
"organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"created_at": "2023-07-06T14:35:58Z"
},
"invoice_custom_section_id": "1a901a90-1a90-1a90-1a90-1a901a901a90"
}
],
"plan": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "Startup",
"created_at": "2023-06-27T19:43:42Z",
"code": "startup",
"interval": "monthly",
"amount_cents": 10000,
"amount_currency": "USD",
"invoice_display_name": "Startup plan",
"description": "Plan for early stage startups.",
"trial_period": 5,
"pay_in_advance": true,
"bill_charges_monthly": null,
"bill_fixed_charges_monthly": null,
"parent_id": null,
"pending_deletion": false,
"minimum_commitment": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"amount_cents": 100000,
"created_at": "2022-04-29T08:59:51Z",
"plan_code": "premium",
"invoice_display_name": "Minimum Commitment (C1)",
"interval": "monthly",
"updated_at": "2022-04-29T08:59:51Z",
"taxes": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "TVA",
"code": "french_standard_vat",
"description": "French standard VAT",
"rate": 20,
"applied_to_organization": true,
"created_at": "2023-07-06T14:35:58Z",
"applied_to_billing_entities_codes": [
"acme_corp",
"foo_bar"
]
}
]
},
"charges": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a91",
"lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a91",
"billable_metric_code": "requests",
"created_at": "2023-06-27T19:43:42Z",
"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
},
"filters": []
},
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a92",
"lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a92",
"billable_metric_code": "cpu",
"created_at": "2023-06-27T19:43:42Z",
"charge_model": "graduated",
"invoiceable": true,
"invoice_display_name": "Setup",
"pay_in_advance": false,
"regroup_paid_fees": null,
"prorated": false,
"min_amount_cents": 0,
"properties": {
"graduated_ranges": [
{
"from_value": 0,
"to_value": 10,
"flat_amount": "10",
"per_unit_amount": "0.5"
},
{
"from_value": 11,
"to_value": null,
"flat_amount": "0",
"per_unit_amount": "0.4"
}
]
},
"filters": []
},
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a93",
"lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a93",
"billable_metric_code": "seats",
"created_at": "2023-06-27T19:43:42Z",
"charge_model": "standard",
"invoiceable": true,
"invoice_display_name": "Setup",
"pay_in_advance": true,
"regroup_paid_fees": null,
"prorated": false,
"min_amount_cents": 0,
"properties": {},
"filters": [
{
"invoice_display_name": "Europe",
"properties": {
"amount": "10"
},
"values": {
"region": [
"Europe"
]
}
},
{
"invoice_display_name": "USA",
"properties": {
"amount": "5"
},
"values": {
"region": [
"USA"
]
}
},
{
"invoice_display_name": "Africa",
"properties": {
"amount": "8"
},
"values": {
"region": [
"Africa"
]
}
}
]
},
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a94",
"lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a94",
"billable_metric_code": "storage",
"created_at": "2023-06-27T19:43:42Z",
"charge_model": "volume",
"invoiceable": true,
"invoice_display_name": "Setup",
"pay_in_advance": false,
"regroup_paid_fees": null,
"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"
}
]
},
"filters": []
},
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a95",
"lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a95",
"billable_metric_code": "payments",
"created_at": "2023-06-27T19:43:42Z",
"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"
},
"filters": []
}
],
"fixed_charges": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"lago_add_on_id": "2b802b80-2b80-2b80-2b80-2b802b802b80",
"code": "setup_fee",
"invoice_display_name": "Setup Fee",
"add_on_code": "setup",
"created_at": "2026-01-15T10:30:00Z",
"charge_model": "standard",
"pay_in_advance": true,
"prorated": false,
"properties": {
"amount": "500"
},
"units": "1.0",
"lago_parent_id": null,
"taxes": [
{
"lago_id": "3c703c70-3c70-3c70-3c70-3c703c703c70",
"name": "VAT",
"code": "vat_20",
"rate": 20,
"description": "Standard VAT rate",
"applied_to_organization": true,
"created_at": "2026-01-01T00:00:00Z"
}
]
},
{
"lago_id": "4d604d60-4d60-4d60-4d60-4d604d604d60",
"lago_add_on_id": "5e505e50-5e50-5e50-5e50-5e505e505e50",
"code": "support_tier",
"invoice_display_name": "Support Tier",
"add_on_code": "premium_support",
"created_at": "2026-01-15T10:30:00Z",
"charge_model": "graduated",
"pay_in_advance": false,
"prorated": true,
"properties": {
"graduated_ranges": [
{
"from_value": 0,
"to_value": 10,
"per_unit_amount": "5",
"flat_amount": "200"
},
{
"from_value": 11,
"to_value": null,
"per_unit_amount": "1",
"flat_amount": "300"
}
]
},
"units": "1.0",
"lago_parent_id": null,
"taxes": []
},
{
"lago_id": "6f406f40-6f40-6f40-6f40-6f406f406f40",
"lago_add_on_id": "7a307a30-7a30-7a30-7a30-7a307a307a30",
"code": "storage",
"invoice_display_name": "Storage Allocation",
"add_on_code": "cloud_storage",
"created_at": "2026-01-15T10:30:00Z",
"charge_model": "volume",
"pay_in_advance": false,
"prorated": false,
"properties": {
"volume_ranges": [
{
"from_value": 0,
"to_value": 100,
"per_unit_amount": "2",
"flat_amount": "1"
},
{
"from_value": 101,
"to_value": null,
"per_unit_amount": "1",
"flat_amount": "0"
}
]
},
"units": "50.0",
"lago_parent_id": null,
"taxes": []
}
],
"taxes": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "TVA",
"code": "french_standard_vat",
"description": "French standard VAT",
"rate": 20,
"applied_to_organization": true,
"created_at": "2023-07-06T14:35:58Z",
"applied_to_billing_entities_codes": [
"acme_corp",
"foo_bar"
]
}
],
"usage_thresholds": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"threshold_display_name": "Threshold 1",
"amount_cents": 10000,
"recurring": true,
"created_at": "2023-06-27T19:43:42Z",
"updated_at": "2023-06-27T19:43:42Z"
}
],
"applicable_usage_thresholds": [
{
"threshold_display_name": "Threshold 1",
"amount_cents": 10000,
"recurring": true
}
],
"entitlements": [
{
"entitlement": {
"code": "seats",
"name": "Number of seats",
"description": "Number of users of the account",
"privileges": [
{
"code": "max",
"name": "Maximum",
"value_type": "integer",
"config": {},
"value": 10
},
{
"code": "max_admins",
"name": "Max Admins",
"value_type": "integer",
"config": {},
"value": 5
},
{
"code": "root",
"name": "Allow root user",
"value_type": "boolean",
"config": {},
"value": true
},
{
"code": "provider",
"name": "SSO Provider",
"value_type": "select",
"value": "google",
"config": {
"select_options": [
"google",
"okta"
]
}
}
]
}
}
],
"metadata": {
"external_id": "ext-123",
"synced_at": "2024-01-15",
"source": null
}
},
"applicable_usage_thresholds": [
{
"threshold_display_name": "Threshold 1",
"amount_cents": 10000,
"recurring": true
}
],
"entitlements": [
{
"code": "seats",
"name": "Number of seats",
"description": "Number of users of the account",
"privileges": [
{
"code": "max",
"name": "Maximum",
"value_type": "integer",
"config": {},
"value": 15,
"plan_value": 10,
"override_value": 15
},
{
"code": "max_admins",
"name": "Max Admins",
"value_type": "integer",
"config": {},
"value": 5,
"plan_value": 5,
"override_value": null
},
{
"code": "root",
"name": "Allow root user",
"value_type": "boolean",
"config": {},
"value": true,
"plan_value": true,
"override_value": null
},
{
"code": "provider",
"name": "SSO Provider",
"value_type": "select",
"value": "okta",
"plan_value": "google",
"override_value": "okta",
"config": {
"select_options": [
"google",
"okta"
]
}
}
],
"overrides": {
"max": 15,
"provider": "okta"
}
}
]
},
"authorization": {
"id": "pi_1a901a901a901a901a901a90",
"object": "payment_intent",
"amount": 5000,
"amount_capturable": 5000,
"status": "requires_capture"
}
}{
"status": 400,
"error": "Bad request"
}{
"status": 401,
"error": "Unauthorized"
}{
"status": 403,
"error": "Forbidden",
"code": "feature_unavailable"
}{
"status": 404,
"error": "Not Found",
"code": "object_not_found"
}{
"status": 405,
"error": "Method Not Allowed",
"code": "not_allowed"
}{
"status": 422,
"error": "Unprocessable entity",
"code": "validation_errors",
"error_details": {}
}Subscriptions
Update a subscription
This endpoint allows you to update a subscription.
PUT
/
subscriptions
/
{external_id}
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
curl --location --request PUT "$LAGO_URL/api/v1/subscriptions/:id" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"subscription": {
"name": "Repository B",
"ending_at": "2022-10-08T00:00:00Z",
"subscription_at": "2022-08-08T00:00:00Z",
"plan_overrides": {
"amount_cents": 10000,
"amount_currency": "USD",
"description": "Plan for early stage startups.",
"invoice_display_name": "Startup plan",
"name": "Startup",
"tax_codes": [
"french_standard_vat"
],
"trial_period": 5,
"charges": [
{
"id": "cha_12345",
"billable_metric_id": "bm_12345",
"invoice_display_name": "Setup",
"min_amount_cents": 0,
"tax_codes": [
"standard_vat"
],
"properties": {
"graduated_ranges": [
{
"from_value": 0,
"to_value": 10,
"flat_amount": "10",
"per_unit_amount": "0.5"
}
]
}
},
{
"id": "cha_67890",
"billable_metric_id": "bm_67890",
"invoice_display_name": "FX Transfer",
"min_amount_cents": 0,
"properties": {
"graduated_percentage_ranges": [
{
"from_value": 0,
"to_value": 10,
"rate": "1",
"flat_amount": "10"
}
]
}
},
{
"id": "cha_111213",
"billable_metric_id": "bm_111213",
"invoice_display_name": "API calls",
"min_amount_cents": 0,
"properties": {
"amount": "30",
"free_units": 100,
"package_size": 1000
}
},
{
"id": "cha_141516",
"billable_metric_id": "bm_141516",
"invoice_display_name": "Interchange",
"min_amount_cents": 0,
"properties": {
"rate": "1",
"fixed_amount": "0.5",
"free_units_per_events": 5,
"free_units_per_total_aggregation": "500",
"per_transaction_max_amount": "3.75",
"per_transaction_min_amount": "1.75"
}
},
{
"id": "cha_171819",
"billable_metric_id": "bm_171819",
"invoice_display_name": "Seats",
"min_amount_cents": 0,
"properties": {
"volume_ranges": [
{
"from_value": 0,
"to_value": 10,
"flat_amount": "10",
"per_unit_amount": "0.5"
}
]
}
},
{
"id": "cha_202122",
"billable_metric_id": "bm_202122",
"invoice_display_name": "Interchange",
"min_amount_cents": 0,
"filters": [
{
"values": {
"cloud": ["aws"],
"region": ["us-east-1"]
},
"properties": {
"graduated_ranges": [
{
"from_value": 0,
"to_value": 10,
"flat_amount": "10",
"per_unit_amount": "0.5"
}
]
}
}
]
}
]
}
}
}'
from lago_python_client.client import Client
from lago_python_client.exceptions import LagoApiError
from lago_python_client.models import Subscription
client = Client(api_key='__YOUR_API_KEY__')
update_params = Subscription(name='new name', subscription_at='2022-08-08T00:00:00Z', ending_at= '2023-08-08T00:00:00Z')
try:
client.subscriptions.update(update_params, 'id')
except LagoApiError as e:
repair_broken_state(e) # do something on error or raise your own exception
require 'lago-ruby-client'
client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')
update_params = { name: 'new name', subscription_at: '2022-08-08T00:00:00Z', ending_at: '2022-08-08T00:00:00Z' }
client.subscriptions.update(update_params, 'id')
await client.subscriptions.updateSubscription("external_id", {
subscription: {
name: "new name",
subscription_at: "2022-08-08T00:00:00Z",
ending_at: "2023-08-08T00:00:00Z",
},
});
{
"subscription": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"billing_time": "anniversary",
"name": "Repository A",
"plan_code": "premium",
"plan_amount_cents": 10000,
"plan_amount_currency": "USD",
"status": "active",
"created_at": "2022-08-08T00:00:00Z",
"canceled_at": "2022-09-14T16:35:31Z",
"started_at": "2022-08-08T00:00:00Z",
"ending_at": "2022-10-08T00:00:00Z",
"subscription_at": "2022-08-08T00:00:00Z",
"terminated_at": "2022-09-14T16:35:31Z",
"previous_plan_code": null,
"next_plan_code": null,
"downgrade_plan_date": "2022-04-30",
"trial_ended_at": "2022-08-08T00:00:00Z",
"current_billing_period_started_at": "2022-08-08T00:00:00Z",
"current_billing_period_ending_at": "2022-09-08T00:00:00Z",
"on_termination_credit_note": "credit",
"on_termination_invoice": "generate",
"payment_method": {
"payment_method_type": "provider",
"payment_method_id": "1a901a90-1a90-1a90-1a90-1a901a901a90"
},
"consolidate_invoice": true,
"progressive_billing_disabled": false,
"cancellation_reason": "payment_failed",
"activated_at": "2022-08-08T00:00:00Z",
"activation_rules": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"type": "payment",
"timeout_hours": 48,
"status": "pending",
"expires_at": "2022-08-10T00:00:00Z",
"created_at": "2022-08-08T00:00:00Z",
"updated_at": "2022-08-08T00:00:00Z"
}
],
"purchase_order_number": "PO-123",
"billing_entity_code": "default",
"applied_invoice_custom_sections": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"created_at": "2023-07-06T14:35:58Z",
"invoice_custom_section": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "EU Bank Details",
"code": "eu_bank_details",
"description": "This section contains the bank details for EU customers.",
"details": "Bank Name: Lago Bank, IBAN: FR7630004000031234567890143",
"display_name": "Bank Details:",
"applied_to_organization": true,
"organization_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"created_at": "2023-07-06T14:35:58Z"
},
"invoice_custom_section_id": "1a901a90-1a90-1a90-1a90-1a901a901a90"
}
],
"plan": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "Startup",
"created_at": "2023-06-27T19:43:42Z",
"code": "startup",
"interval": "monthly",
"amount_cents": 10000,
"amount_currency": "USD",
"invoice_display_name": "Startup plan",
"description": "Plan for early stage startups.",
"trial_period": 5,
"pay_in_advance": true,
"bill_charges_monthly": null,
"bill_fixed_charges_monthly": null,
"parent_id": null,
"pending_deletion": false,
"minimum_commitment": {
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"amount_cents": 100000,
"created_at": "2022-04-29T08:59:51Z",
"plan_code": "premium",
"invoice_display_name": "Minimum Commitment (C1)",
"interval": "monthly",
"updated_at": "2022-04-29T08:59:51Z",
"taxes": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "TVA",
"code": "french_standard_vat",
"description": "French standard VAT",
"rate": 20,
"applied_to_organization": true,
"created_at": "2023-07-06T14:35:58Z",
"applied_to_billing_entities_codes": [
"acme_corp",
"foo_bar"
]
}
]
},
"charges": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a91",
"lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a91",
"billable_metric_code": "requests",
"created_at": "2023-06-27T19:43:42Z",
"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
},
"filters": []
},
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a92",
"lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a92",
"billable_metric_code": "cpu",
"created_at": "2023-06-27T19:43:42Z",
"charge_model": "graduated",
"invoiceable": true,
"invoice_display_name": "Setup",
"pay_in_advance": false,
"regroup_paid_fees": null,
"prorated": false,
"min_amount_cents": 0,
"properties": {
"graduated_ranges": [
{
"from_value": 0,
"to_value": 10,
"flat_amount": "10",
"per_unit_amount": "0.5"
},
{
"from_value": 11,
"to_value": null,
"flat_amount": "0",
"per_unit_amount": "0.4"
}
]
},
"filters": []
},
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a93",
"lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a93",
"billable_metric_code": "seats",
"created_at": "2023-06-27T19:43:42Z",
"charge_model": "standard",
"invoiceable": true,
"invoice_display_name": "Setup",
"pay_in_advance": true,
"regroup_paid_fees": null,
"prorated": false,
"min_amount_cents": 0,
"properties": {},
"filters": [
{
"invoice_display_name": "Europe",
"properties": {
"amount": "10"
},
"values": {
"region": [
"Europe"
]
}
},
{
"invoice_display_name": "USA",
"properties": {
"amount": "5"
},
"values": {
"region": [
"USA"
]
}
},
{
"invoice_display_name": "Africa",
"properties": {
"amount": "8"
},
"values": {
"region": [
"Africa"
]
}
}
]
},
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a94",
"lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a94",
"billable_metric_code": "storage",
"created_at": "2023-06-27T19:43:42Z",
"charge_model": "volume",
"invoiceable": true,
"invoice_display_name": "Setup",
"pay_in_advance": false,
"regroup_paid_fees": null,
"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"
}
]
},
"filters": []
},
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a95",
"lago_billable_metric_id": "1a901a90-1a90-1a90-1a90-1a901a901a95",
"billable_metric_code": "payments",
"created_at": "2023-06-27T19:43:42Z",
"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"
},
"filters": []
}
],
"fixed_charges": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"lago_add_on_id": "2b802b80-2b80-2b80-2b80-2b802b802b80",
"code": "setup_fee",
"invoice_display_name": "Setup Fee",
"add_on_code": "setup",
"created_at": "2026-01-15T10:30:00Z",
"charge_model": "standard",
"pay_in_advance": true,
"prorated": false,
"properties": {
"amount": "500"
},
"units": "1.0",
"lago_parent_id": null,
"taxes": [
{
"lago_id": "3c703c70-3c70-3c70-3c70-3c703c703c70",
"name": "VAT",
"code": "vat_20",
"rate": 20,
"description": "Standard VAT rate",
"applied_to_organization": true,
"created_at": "2026-01-01T00:00:00Z"
}
]
},
{
"lago_id": "4d604d60-4d60-4d60-4d60-4d604d604d60",
"lago_add_on_id": "5e505e50-5e50-5e50-5e50-5e505e505e50",
"code": "support_tier",
"invoice_display_name": "Support Tier",
"add_on_code": "premium_support",
"created_at": "2026-01-15T10:30:00Z",
"charge_model": "graduated",
"pay_in_advance": false,
"prorated": true,
"properties": {
"graduated_ranges": [
{
"from_value": 0,
"to_value": 10,
"per_unit_amount": "5",
"flat_amount": "200"
},
{
"from_value": 11,
"to_value": null,
"per_unit_amount": "1",
"flat_amount": "300"
}
]
},
"units": "1.0",
"lago_parent_id": null,
"taxes": []
},
{
"lago_id": "6f406f40-6f40-6f40-6f40-6f406f406f40",
"lago_add_on_id": "7a307a30-7a30-7a30-7a30-7a307a307a30",
"code": "storage",
"invoice_display_name": "Storage Allocation",
"add_on_code": "cloud_storage",
"created_at": "2026-01-15T10:30:00Z",
"charge_model": "volume",
"pay_in_advance": false,
"prorated": false,
"properties": {
"volume_ranges": [
{
"from_value": 0,
"to_value": 100,
"per_unit_amount": "2",
"flat_amount": "1"
},
{
"from_value": 101,
"to_value": null,
"per_unit_amount": "1",
"flat_amount": "0"
}
]
},
"units": "50.0",
"lago_parent_id": null,
"taxes": []
}
],
"taxes": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "TVA",
"code": "french_standard_vat",
"description": "French standard VAT",
"rate": 20,
"applied_to_organization": true,
"created_at": "2023-07-06T14:35:58Z",
"applied_to_billing_entities_codes": [
"acme_corp",
"foo_bar"
]
}
],
"usage_thresholds": [
{
"lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"threshold_display_name": "Threshold 1",
"amount_cents": 10000,
"recurring": true,
"created_at": "2023-06-27T19:43:42Z",
"updated_at": "2023-06-27T19:43:42Z"
}
],
"applicable_usage_thresholds": [
{
"threshold_display_name": "Threshold 1",
"amount_cents": 10000,
"recurring": true
}
],
"entitlements": [
{
"entitlement": {
"code": "seats",
"name": "Number of seats",
"description": "Number of users of the account",
"privileges": [
{
"code": "max",
"name": "Maximum",
"value_type": "integer",
"config": {},
"value": 10
},
{
"code": "max_admins",
"name": "Max Admins",
"value_type": "integer",
"config": {},
"value": 5
},
{
"code": "root",
"name": "Allow root user",
"value_type": "boolean",
"config": {},
"value": true
},
{
"code": "provider",
"name": "SSO Provider",
"value_type": "select",
"value": "google",
"config": {
"select_options": [
"google",
"okta"
]
}
}
]
}
}
],
"metadata": {
"external_id": "ext-123",
"synced_at": "2024-01-15",
"source": null
}
},
"applicable_usage_thresholds": [
{
"threshold_display_name": "Threshold 1",
"amount_cents": 10000,
"recurring": true
}
],
"entitlements": [
{
"code": "seats",
"name": "Number of seats",
"description": "Number of users of the account",
"privileges": [
{
"code": "max",
"name": "Maximum",
"value_type": "integer",
"config": {},
"value": 15,
"plan_value": 10,
"override_value": 15
},
{
"code": "max_admins",
"name": "Max Admins",
"value_type": "integer",
"config": {},
"value": 5,
"plan_value": 5,
"override_value": null
},
{
"code": "root",
"name": "Allow root user",
"value_type": "boolean",
"config": {},
"value": true,
"plan_value": true,
"override_value": null
},
{
"code": "provider",
"name": "SSO Provider",
"value_type": "select",
"value": "okta",
"plan_value": "google",
"override_value": "okta",
"config": {
"select_options": [
"google",
"okta"
]
}
}
],
"overrides": {
"max": 15,
"provider": "okta"
}
}
]
},
"authorization": {
"id": "pi_1a901a901a901a901a901a90",
"object": "payment_intent",
"amount": 5000,
"amount_capturable": 5000,
"status": "requires_capture"
}
}{
"status": 400,
"error": "Bad request"
}{
"status": 401,
"error": "Unauthorized"
}{
"status": 403,
"error": "Forbidden",
"code": "feature_unavailable"
}{
"status": 404,
"error": "Not Found",
"code": "object_not_found"
}{
"status": 405,
"error": "Method Not Allowed",
"code": "not_allowed"
}{
"status": 422,
"error": "Unprocessable entity",
"code": "validation_errors",
"error_details": {}
}LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"
curl --location --request PUT "$LAGO_URL/api/v1/subscriptions/:id" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"subscription": {
"name": "Repository B",
"ending_at": "2022-10-08T00:00:00Z",
"subscription_at": "2022-08-08T00:00:00Z",
"plan_overrides": {
"amount_cents": 10000,
"amount_currency": "USD",
"description": "Plan for early stage startups.",
"invoice_display_name": "Startup plan",
"name": "Startup",
"tax_codes": [
"french_standard_vat"
],
"trial_period": 5,
"charges": [
{
"id": "cha_12345",
"billable_metric_id": "bm_12345",
"invoice_display_name": "Setup",
"min_amount_cents": 0,
"tax_codes": [
"standard_vat"
],
"properties": {
"graduated_ranges": [
{
"from_value": 0,
"to_value": 10,
"flat_amount": "10",
"per_unit_amount": "0.5"
}
]
}
},
{
"id": "cha_67890",
"billable_metric_id": "bm_67890",
"invoice_display_name": "FX Transfer",
"min_amount_cents": 0,
"properties": {
"graduated_percentage_ranges": [
{
"from_value": 0,
"to_value": 10,
"rate": "1",
"flat_amount": "10"
}
]
}
},
{
"id": "cha_111213",
"billable_metric_id": "bm_111213",
"invoice_display_name": "API calls",
"min_amount_cents": 0,
"properties": {
"amount": "30",
"free_units": 100,
"package_size": 1000
}
},
{
"id": "cha_141516",
"billable_metric_id": "bm_141516",
"invoice_display_name": "Interchange",
"min_amount_cents": 0,
"properties": {
"rate": "1",
"fixed_amount": "0.5",
"free_units_per_events": 5,
"free_units_per_total_aggregation": "500",
"per_transaction_max_amount": "3.75",
"per_transaction_min_amount": "1.75"
}
},
{
"id": "cha_171819",
"billable_metric_id": "bm_171819",
"invoice_display_name": "Seats",
"min_amount_cents": 0,
"properties": {
"volume_ranges": [
{
"from_value": 0,
"to_value": 10,
"flat_amount": "10",
"per_unit_amount": "0.5"
}
]
}
},
{
"id": "cha_202122",
"billable_metric_id": "bm_202122",
"invoice_display_name": "Interchange",
"min_amount_cents": 0,
"filters": [
{
"values": {
"cloud": ["aws"],
"region": ["us-east-1"]
},
"properties": {
"graduated_ranges": [
{
"from_value": 0,
"to_value": 10,
"flat_amount": "10",
"per_unit_amount": "0.5"
}
]
}
}
]
}
]
}
}
}'
from lago_python_client.client import Client
from lago_python_client.exceptions import LagoApiError
from lago_python_client.models import Subscription
client = Client(api_key='__YOUR_API_KEY__')
update_params = Subscription(name='new name', subscription_at='2022-08-08T00:00:00Z', ending_at= '2023-08-08T00:00:00Z')
try:
client.subscriptions.update(update_params, 'id')
except LagoApiError as e:
repair_broken_state(e) # do something on error or raise your own exception
require 'lago-ruby-client'
client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')
update_params = { name: 'new name', subscription_at: '2022-08-08T00:00:00Z', ending_at: '2022-08-08T00:00:00Z' }
client.subscriptions.update(update_params, 'id')
await client.subscriptions.updateSubscription("external_id", {
subscription: {
name: "new name",
subscription_at: "2022-08-08T00:00:00Z",
ending_at: "2023-08-08T00:00:00Z",
},
});
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
External ID of the existing subscription
Example:
"5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"
Query Parameters
By default, this endpoint only updates active subscriptions. If you want to update a subscription with a different status, you can specify it here.
Available options:
active, pending Example:
"active"
Body
application/json
Update an existing subscription
Show child attributes
Show child attributes
If the field is not defined and multiple active and pending subscriptions exists, Lago will update the active subscription. However, if you wish to update a pending subscription, please ensure that you include the status attribute with the pending value in your request body.
Available options:
active, pending Example:
"active"