Update a subscription

This endpoint allows you to update a subscription.

PUT /subscriptions/{external_id}

cURL

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"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }
}'

200

{
  "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"
  }
}

cURL

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"
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  }
}'

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

external_id · string · required

External ID of the existing subscription

Example:

"5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"

Query Parameters

status · enum<string> · default: active

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

subscription · object · required

Show child attributes

status · enum<string>

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"

Response

200

application/json

Subscription updated

subscription · object · required

Show child attributes

authorization · object

The Stripe payment intent created for the pre-authorization. Only returned when creating a subscription with an authorization payload.

Show child attributes