Update subscription lifetime usage

API Reference

Getting started
Add-ons
Analytics
Billable metrics
Coupons
Credit notes
Customer usage
Customers
Events
Fees
Invoices
Organizations
Payments
Payment receipts
Payment requests
Plans
Resources
Subscriptions
- The subscription object
- POST
  Create a subscription
- PUT
  Update a subscription
- DEL
  Terminate a subscription
- GET
  Retrieve a subscription
- GET
  List all subscriptions
- The lifetime usage object
- GET
  Retrieve subscription lifetime usage
- PUT
  Update subscription lifetime usage
Taxes
Wallets
Webhook endpoints
Webhooks

PUT

subscriptions

{external_id}

lifetime_usage

curl --request PUT \
  --url https://api.getlago.com/api/v1/subscriptions/{external_id}/lifetime_usage \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "lifetime_usage": {
    "external_historical_usage_amount_cents": 100
  }
}'

{
  "lifetime_usage": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "lago_subscription_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "external_subscription_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "external_historical_usage_amount_cents": 100,
    "invoiced_usage_amount_cents": 100,
    "current_usage_amount_cents": 100,
    "from_datetime": "2024-01-01T00:00:00Z",
    "to_datetime": "2024-12-31T23:59:59Z",
    "usage_thresholds": [
      {
        "amount_cents": 100,
        "completion_ratio": 0.5,
        "reached_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

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"

Body

application/json

Update the lifetime usage of a subscription

lifetime_usage

object

required

Response

200

application/json

Subscription lifetime usage updated

lifetime_usage

object

required

lifetime_usage.lago_id

string

required

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

Example:

"1a901a90-1a90-1a90-1a90-1a901a901a90"

lifetime_usage.lago_subscription_id

string

required

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

Example:

"1a901a90-1a90-1a90-1a90-1a901a901a90"

lifetime_usage.external_subscription_id

string

required

The subscription external unique identifier (provided by your own application).

Example:

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

lifetime_usage.external_historical_usage_amount_cents

integer

required

The historical usage amount in cents for the subscription (provided by your own application).

Example:

100

lifetime_usage.invoiced_usage_amount_cents

integer

required

The total invoiced usage amount in cents for the subscription.

Example:

100

lifetime_usage.current_usage_amount_cents

integer

required

The current usage amount in cents for the subscription on the current billing period.

Example:

100

lifetime_usage.from_datetime

string

required

The recording start date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format.

Example:

"2024-01-01T00:00:00Z"

lifetime_usage.to_datetime

string

required

The recording end date and time of the subscription lifetime usage. The date and time must be in ISO 8601 format.

Example:

"2024-12-31T23:59:59Z"

lifetime_usage.usage_thresholds

object[]

Array of usage thresholds attached to the subscription's plan.

Was this page helpful?

Suggest edits Raise issue

Retrieve subscription lifetime usage The tax object

curl --request PUT \
  --url https://api.getlago.com/api/v1/subscriptions/{external_id}/lifetime_usage \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "lifetime_usage": {
    "external_historical_usage_amount_cents": 100
  }
}'

{
  "lifetime_usage": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "lago_subscription_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "external_subscription_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "external_historical_usage_amount_cents": 100,
    "invoiced_usage_amount_cents": 100,
    "current_usage_amount_cents": 100,
    "from_datetime": "2024-01-01T00:00:00Z",
    "to_datetime": "2024-12-31T23:59:59Z",
    "usage_thresholds": [
      {
        "amount_cents": 100,
        "completion_ratio": 0.5,
        "reached_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}