List all subscriptions

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request GET "$LAGO_URL/api/v1/subscriptions?external_customer_id=123&plan_code=starter&status[]=pending" \
  --header "Authorization: Bearer $API_KEY"

from lago_python_client.client import Client
from lago_python_client.exceptions import LagoApiError

client = Client(api_key='__YOUR_API_KEY__')

try:
    client.subscriptions.find_all({'external_customer_id': '123'})
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__')

client.subscriptions.get_all({ external_customer_id: '123'})

await client.subscriptions.findAllSubscriptions({
  external_customer_id: "123",
  page: 1,
});

{
  "subscriptions": [
    {
      "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"
        }
      ]
    }
  ],
  "meta": {
    "current_page": 2,
    "total_pages": 4,
    "total_count": 70,
    "next_page": 3,
    "prev_page": 1
  }
}

{
  "status": 401,
  "error": "Unauthorized"
}

{
  "status": 404,
  "error": "Not Found",
  "code": "object_not_found"
}

GET

subscriptions

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request GET "$LAGO_URL/api/v1/subscriptions?external_customer_id=123&plan_code=starter&status[]=pending" \
  --header "Authorization: Bearer $API_KEY"

from lago_python_client.client import Client
from lago_python_client.exceptions import LagoApiError

client = Client(api_key='__YOUR_API_KEY__')

try:
    client.subscriptions.find_all({'external_customer_id': '123'})
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__')

client.subscriptions.get_all({ external_customer_id: '123'})

await client.subscriptions.findAllSubscriptions({
  external_customer_id: "123",
  page: 1,
});

{
  "subscriptions": [
    {
      "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"
        }
      ]
    }
  ],
  "meta": {
    "current_page": 2,
    "total_pages": 4,
    "total_count": 70,
    "next_page": 3,
    "prev_page": 1
  }
}

{
  "status": 401,
  "error": "Unauthorized"
}

{
  "status": 404,
  "error": "Not Found",
  "code": "object_not_found"
}

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request GET "$LAGO_URL/api/v1/subscriptions?external_customer_id=123&plan_code=starter&status[]=pending" \
  --header "Authorization: Bearer $API_KEY"

from lago_python_client.client import Client
from lago_python_client.exceptions import LagoApiError

client = Client(api_key='__YOUR_API_KEY__')

try:
    client.subscriptions.find_all({'external_customer_id': '123'})
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__')

client.subscriptions.get_all({ external_customer_id: '123'})

await client.subscriptions.findAllSubscriptions({
  external_customer_id: "123",
  page: 1,
});

Authorizations

Authorization

string

header

required

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

Query Parameters

page

integer

Page number. Defaults to 1. A value that is not a positive integer, such as 0, returns the first page.

Example:

1

per_page

integer

Number of records per page. Defaults to 100. The maximum is 200, unless another maximum is configured for your organization. A value above the maximum returns a 422 error with value_is_out_of_range on per_page. A value that is not a positive integer, such as 0, returns the default number of records.

Example:

20

currency

string

Filter the results by currency, expressed as an ISO 4217 code.

Example:

"EUR"

external_customer_id

string

The customer external unique identifier (provided by your own application)

Example:

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

external_id

string

Filter subscriptions by their external unique identifier (provided by your own application).

Example:

"my_sub_1234567890"

plan_code

string

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.

Example:

"premium"

overridden

boolean

When set, filters subscriptions by whether their plan is an override of a parent plan. true returns only subscriptions on overridden plans; false returns only those on standard (non-overridden) plans.

Example:

true

status[]

enum<string>[]

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, incomplete.

Available options:

active,

canceled,

incomplete,

pending,

terminated

Example:

["active", "pending"]

billing_entity_codes[]

string[]

Filter subscriptions by billing entity codes. A code that does not match a billing entity of the organization returns a 404 error.

Example:

[
  "billing_entity_code_1",
  "billing_entity_code_2"
]

Response

List of subscriptions

subscriptions

object[]

required

Show child attributes