lago-javascript-client 1.54.0 → 1.56.0

package/script/openapi/client.js

@@ -160,7 +160,7 @@ class HttpClient {
 exports.HttpClient = HttpClient;
 /**
  * @title Lago API documentation
- * @version 1.54.0
+ * @version 1.56.0
  * @license AGPLv3 (https://github.com/getlago/lago-openapi/blob/main/LICENSE)
  * @baseUrl https://api.getlago.com/api/v1
  * @externalDocs https://github.com/getlago
@@ -345,7 +345,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint is used to delete an existing add-on.
+         * @description This endpoint is used to delete an existing add-on. The fixed charges that use this add-on are deleted too.
          *
          * @tags add_ons
          * @name DestroyAddOn
@@ -363,11 +363,11 @@ class Api extends HttpClient {
     };
     apiLogs = {
         /**
-         * @description This endpoint retrieves all existing api logs that represent requests performed to Lago's API.
+         * @description This endpoint retrieves all existing API logs, which represent the requests made to Lago's API. Logs older than the retention period of your organization are left out. The retention period is 30 days unless another one was set for your organization.
          *
          * @tags api_logs
          * @name FindAllApiLogs
-         * @summary List all api logs
+         * @summary List all API logs
          * @request GET:/api_logs
          * @secure
          */
@@ -380,11 +380,11 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint retrieves an existing api log that represents a request made to the API. The api log is identified by its unique request_id.
+         * @description This endpoint retrieves an existing API log, which represents a request made to Lago's API. The API log is identified by its request id.
          *
          * @tags api_logs
          * @name FindApiLog
-         * @summary Retrieve an api log
+         * @summary Retrieve an API log
          * @request GET:/api_logs/{request_id}
          * @secure
          */
@@ -398,7 +398,7 @@ class Api extends HttpClient {
     };
     analytics = {
         /**
-         * @description Gross revenue is the sum of monthly `finalized` invoice payments and fees paid in advance that are not invoiceable. This total is calculated after deducting taxes and discounts.
+         * @description Gross revenue is the monthly sum of the totals of `finalized` invoices and of the amounts of the fees paid in advance that are not attached to an invoice. Invoice totals include taxes, are net of coupons, and are reduced by the amounts refunded through credit notes. Self-billed invoices and invoices with a lost payment dispute are excluded.
          *
          * @tags analytics
          * @name FindAllGrossRevenues
@@ -415,7 +415,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description Represents a monthly aggregation, detailing both the total count and the cumulative amount of invoices that have been marked as `finalized`. This report sorts invoices categorically based on their `payment_status`.
+         * @description Represents a monthly aggregation, detailing both the total count and the cumulative amount of invoices that have been marked as `finalized`. This report sorts invoices categorically based on their `payment_status`. Self-billed invoices and invoices with a lost payment dispute are excluded. This is a premium feature.
          *
          * @tags analytics
          * @name FindAllInvoiceCollections
@@ -432,7 +432,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description Reports a monthly analysis focused on the revenue generated from all usage-based fees. It exclusively accounts for revenue that has been formally invoiced. Importantly, this report does not include revenue related to the usage in the current billing period, limiting its scope to previously invoiced amounts.
+         * @description Reports the monthly revenue generated by usage-based fees, broken down by billable metric. It only counts usage that has already been invoiced, so the usage of the current billing period is not included. Amounts exclude taxes and are net of coupons. Fees on self-billed invoices and on invoices with a lost payment dispute are left out.
          *
          * @tags analytics
          * @name FindAllInvoicedUsages
@@ -449,7 +449,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint is used to list MRR.
+         * @description Quantifies the revenue generated from `subscription` fees on a monthly basis. This figure is calculated post-application of applicable taxes and deduction of any applicable discounts. The method of calculation varies based on the subscription billing cycle: - Revenue from `monthly` subscription invoices is included in the MRR for the month in which the invoice is issued. - Revenue from `quarterly` subscription invoices is distributed evenly over three months. This distribution applies to fees paid in advance (allocated to the next remaining months depending on calendar or anniversary billing) as well as to fees paid in arrears (allocated to the preceding months depending on calendar or anniversary billing). - Revenue from `yearly` subscription invoices is distributed evenly over twelve months. This allocation is applicable for fees paid in advance (spread over the next remaining months depending on calendar or anniversary billing) and for fees paid in arrears (spread over the previous months depending on calendar or anniversary billing). - Revenue from `semiannual` subscription invoices is distributed evenly over six months. This allocation is applicable for fees paid in advance (spread over the next remaining months depending on calendar or anniversary billing) and for fees paid in arrears (spread over the previous months depending on calendar or anniversary billing). - Revenue from `weekly` subscription invoices, the total revenue from all invoices issued within a month is summed up. This total is then divided by the number of invoices issued during that month, and the result is multiplied by 4.33, representing the average number of weeks in a month.
          *
          * @tags analytics
          * @name FindAllMrrs
@@ -466,7 +466,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description Overdue balance is the total amount associated with overdue invoices (invoices with pending or failed payments which are past their due dates).
+         * @description Overdue balance is the amount still due on invoices that are past their payment due date. Each entry covers one month of payment due dates and sums the invoice totals minus the amounts already paid and minus the credits applied by finalized credit notes. Self-billed invoices are excluded.
          *
          * @tags analytics
          * @name FindAllOverdueBalances
@@ -483,7 +483,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description Returns usages.
+         * @description Returns the usage billed by each billable metric, aggregated over the requested period and time granularity. This is a premium feature. On a non-premium license the response always covers the last 30 days with a daily granularity, and only the `billable_metric_code` filter is applied.
          *
          * @tags analytics
          * @name FindAllUsages
@@ -592,7 +592,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint updates an existing billable metric representing a pricing component of your application.
+         * @description This endpoint updates an existing billable metric representing a pricing component of your application. Once the billable metric is used by a plan charge, only `name`, `description` and `filters` are applied. The other fields are ignored.
          *
          * @tags billable_metrics
          * @name UpdateBillableMetric
@@ -679,7 +679,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint updates an existing feature representing an entitlement component of your application.
+         * @description This endpoint updates an existing feature representing an entitlement component of your application. Only the fields present in the payload are updated. Privileges are matched by their code, an unknown code adds a new privilege and a known one updates its name and adds the select options of the payload to the existing ones. The value type of an existing privilege cannot be changed. Privileges left out of the payload are kept, use the delete privilege endpoint to remove one.
          *
          * @tags features
          * @name UpdateFeature
@@ -729,11 +729,11 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description Delete privilege from feature. Deleting a privilege removes it from all plans and subscriptions.
+         * @description This endpoint deletes a privilege from a feature. Deleting a privilege removes it from all plans and subscriptions.
          *
          * @tags features
          * @name DeleteFeaturePrivilege
-         * @summary Delete a privilege. Deleting a privilege removes it from all plans and subscriptions.
+         * @summary Delete a privilege
          * @request DELETE:/features/{code}/privileges/{privilege_code}
          * @secure
          */
@@ -782,7 +782,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint is used to update a coupon that can be then attached to a customer to create a discount.
+         * @description This endpoint is used to update a coupon that can be then attached to a customer to create a discount. Once the coupon has been applied to at least one customer, only `name`, `description`, `expiration` and `expiration_at` are updated. The other fields in the payload are ignored.
          *
          * @tags coupons
          * @name UpdateCoupon
@@ -834,7 +834,7 @@ class Api extends HttpClient {
     };
     creditNotes = {
         /**
-         * @description This endpoint creates a new credit note.
+         * @description This endpoint creates a new credit note. This is a premium feature. A credit note cannot be issued on an invoice in a `pending` or `failed` status. In that case the endpoint returns a `405` error with the `invalid_type_or_status` code.
          *
          * @tags credit_notes
          * @name CreateCreditNote
@@ -852,7 +852,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint list all existing credit notes.
+         * @description This endpoint lists all existing credit notes.
          *
          * @tags credit_notes
          * @name FindAllCreditNotes
@@ -903,7 +903,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint downloads the PDF of an existing credit note.
+         * @description This endpoint downloads the PDF of an existing credit note. Only `finalized` credit notes can be downloaded; any other credit note returns a `404` error. When the PDF has already been generated, the credit note object is returned and its `file_url` points to the document. When it has not been generated yet, the response is a `200` with an empty body and the generation starts in the background. Call the endpoint again to get the credit note object with its `file_url`.
          *
          * @tags credit_notes
          * @name DownloadCreditNote
@@ -919,7 +919,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint allows you to retrieve amounts for a new credit note creation.
+         * @description This endpoint allows you to retrieve amounts for a new credit note creation. This is a premium feature. Amounts cannot be estimated on an invoice in a `pending` or `failed` status. In that case the endpoint returns a `405` error with the `invalid_type_or_status` code.
          *
          * @tags credit_notes
          * @name EstimateCreditNote
@@ -1023,7 +1023,7 @@ class Api extends HttpClient {
     };
     customers = {
         /**
-         * @description This endpoint creates a new customer.
+         * @description This endpoint creates a customer. When a customer with the same `external_id` already exists, it is updated instead, and only the fields present in the payload are changed.
          *
          * @tags customers
          * @name CreateCustomer
@@ -1123,7 +1123,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint list all existing credit notes for a customer.
+         * @description This endpoint lists all existing credit notes for a customer.
          *
          * @tags customers, credit_notes
          * @name FindAllCustomerCreditNotes
@@ -1191,7 +1191,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description Retrieves an embeddable link for displaying a customer portal. This endpoint allows you to fetch the URL that can be embedded to provide customers access to a dedicated portal
+         * @description Retrieves an embeddable link for displaying a customer portal. This endpoint allows you to fetch the URL that can be embedded to provide customers access to a dedicated portal. The portal lets the customer update their information and top up their wallets, so when API key permissions are enabled, the API key needs the `write` permission on `customer`.
          *
          * @tags customers
          * @name GetCustomerPortalUrl
@@ -1242,7 +1242,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint is used to list all wallets with prepaid credits of a customer
+         * @description This endpoint is used to list all wallets with prepaid credits of a customer.
          *
          * @tags wallets
          * @name FindAllCustomerWallets
@@ -1443,7 +1443,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint allows you to update an existing alert for a wallet.
+         * @description This endpoint allows you to update an existing alert for a wallet. A non-empty `thresholds` array replaces the whole set of thresholds on the alert. When `thresholds` is left out, or sent as an empty array, the thresholds already on the alert are kept. A threshold sent with a `code` it already had, and without `notify_on`, keeps the `notify_on` it had.
          *
          * @tags wallets
          * @name UpdateCustomerWalletAlert
@@ -1544,7 +1544,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint retrieves all payment methods of a Customer.
+         * @description This endpoint retrieves all payment methods of a customer.
          *
          * @tags payment_methods
          * @name FindAllCustomersPaymentMethods
@@ -1595,11 +1595,11 @@ class Api extends HttpClient {
     };
     events = {
         /**
-         * @description This endpoint is used for transmitting usage measurement events to either a designated customer or a specific subscription.
+         * @description This endpoint is used for transmitting a usage measurement event to a subscription.
          *
          * @tags events
          * @name CreateEvent
-         * @summary Send usage events
+         * @summary Send a usage event
          * @request POST:/events
          * @secure
          */
@@ -1702,7 +1702,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint is used for retrieving a specific usage measurement event that has been sent to a customer or a subscription. Note that transaction_id is unique per external_subscription_id so multiple subscriptions can share the same transaction_id. This endpoint will only return the first event found with the given transaction_id. WARNING: If your Lago organization is configured to use the Clickhouse-based event pipeline, multiple events can share the same `transaction_id` (with different timestamps). This endpoint will only return the first event found.
+         * @description This endpoint is used for retrieving a specific usage measurement event that has been sent to a subscription. Note that transaction_id is unique per external_subscription_id so multiple subscriptions can share the same transaction_id. This endpoint will only return the first event found with the given transaction_id. WARNING: If your Lago organization is configured to use the Clickhouse-based event pipeline, multiple events can share the same `transaction_id` (with different timestamps). This endpoint will only return the first event found.
          *
          * @tags events
          * @name FindEvent
@@ -1753,7 +1753,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint is used for updating a specific fee that has been issued.
+         * @description This endpoint is used for updating the payment status of a specific fee. Only a fee that is not attached to an invoice can be updated; once the fee is on an invoice, its payment status follows the invoice and the endpoint returns a `405` error.
          *
          * @tags fees
          * @name UpdateFee
@@ -1874,7 +1874,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint is used for downloading a specific invoice PDF document.
+         * @description This endpoint is used for downloading a specific invoice PDF document. Only `finalized` invoices can be downloaded; any other invoice returns a `404` error. When the PDF has already been generated, the invoice object is returned and its `file_url` points to the document. When it has not been generated yet, the response is a `200` with an empty body and the generation starts in the background. Call the endpoint again to get the invoice object with its `file_url`.
          *
          * @tags invoices
          * @name DownloadInvoice
@@ -2163,7 +2163,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint is used to update your own organization's settings.
+         * @description This endpoint is used to update your own organization's settings. The same payload is also applied to the default billing entity of your organization.
          *
          * @tags organizations
          * @name UpdateOrganization
@@ -2218,7 +2218,7 @@ class Api extends HttpClient {
     };
     paymentRequests = {
         /**
-         * @description This endpoint is used to create a payment request to collect payments of overdue invoices of a given customer
+         * @description This endpoint is used to create a payment request to collect the payment of the overdue invoices of a customer.
          *
          * @tags payment_requests
          * @name CreatePaymentRequest
@@ -2409,7 +2409,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint creates new entitlements by adding features to a plan. Note that all existing entitlements will be deleted and replaced by the ones provided. To add a new entitlement without removing the existing ones, use PATCH. The feature must exist and all privileges must be valid for the feature.
+         * @description This endpoint creates new entitlements by adding features to a plan. Note that all existing entitlements will be deleted and replaced by the ones provided. Sending an empty `entitlements` object, or omitting the key, therefore removes every entitlement of the plan. To add a new entitlement without removing the existing ones, use PATCH. The feature must exist and all privileges must be valid for the feature.
          *
          * @tags entitlements
          * @name CreateEntitlement
@@ -2443,7 +2443,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This accepts a list of entitlements to update. If the feature isn't part of the plan yet, it's added with all the privileges from the payload. If the feature is already part of the plan, the privilege and values are updated or added. All privileges must be valid for the feature. All features  and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints.
+         * @description This accepts a list of entitlements to update. If the feature isn't part of the plan yet, it's added with all the privileges from the payload. If the feature is already part of the plan, the privilege and values are updated or added. All privileges must be valid for the feature. All features and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints.
          *
          * @tags entitlements
          * @name UpdateEntitlement
@@ -2628,7 +2628,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint updates a specific charge for a plan.
+         * @description This endpoint updates a specific charge for a plan. The payload replaces the charge configuration: `charge_model` must be sent on every update, and `invoice_display_name` is cleared when it is left out. Once the plan is attached to a subscription, only `invoice_display_name`, `properties`, `filters`, `tax_codes`, `applied_pricing_unit` and `accepts_target_wallet` are applied. The other fields are ignored.
          *
          * @tags plans
          * @name UpdatePlanCharge
@@ -2802,7 +2802,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint updates a specific fixed charge for a plan.
+         * @description This endpoint updates a specific fixed charge for a plan. The payload replaces the fixed charge configuration: `units` and `charge_model` must be sent on every update, and `invoice_display_name` is cleared when it is left out. Once the plan is attached to a subscription, `code` and `charge_model` are ignored.
          *
          * @tags plans
          * @name UpdatePlanFixedCharge
@@ -3151,7 +3151,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint allows you to update an existing alert for a subscription.
+         * @description This endpoint allows you to update an existing alert for a subscription. A non-empty `thresholds` array replaces the whole set of thresholds on the alert. When `thresholds` is left out, or sent as an empty array, the thresholds already on the alert are kept. A threshold sent with a `code` it already had, and without `notify_on`, keeps the `notify_on` it had.
          *
          * @tags subscriptions
          * @name UpdateSubscriptionAlert
@@ -3204,7 +3204,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This accepts a list of entitlements to update. If the feature isn't part of the subscription yet, it's added with all the privileges from the payload. If the feature is already part of the subscription (via plan or via override), the privilege and values are updated or added. All privileges must be valid for the feature. All features  and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints.
+         * @description This accepts a list of entitlements to update. If the feature isn't part of the subscription yet, it's added with all the privileges from the payload. If the feature is already part of the subscription (via plan or via override), the privilege and values are updated or added. All privileges must be valid for the feature. All features and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints.
          *
          * @tags entitlements
          * @name UpdateSubscriptionEntitlements
@@ -3223,7 +3223,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint removes a specific feature entitlement from a subscription. The entitlement remains available from the plan.
+         * @description This endpoint removes a specific feature entitlement from a subscription. The plan keeps the feature and other subscriptions are not affected, but this subscription stops getting it. It returns the full list of entitlements remaining on the subscription.
          *
          * @tags entitlements
          * @name DestroySubscriptionEntitlement
@@ -3240,7 +3240,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint removes a specific privilege from a subscription entitlement. The privilege entitlement remains available from the plan.
+         * @description This endpoint removes a specific privilege from a subscription entitlement. The plan keeps the privilege and other subscriptions are not affected, but this subscription stops getting it. It returns the full list of entitlements remaining on the subscription.
          *
          * @tags entitlements
          * @name DestroySubscriptionEntitlementPrivilege
@@ -3454,7 +3454,7 @@ class Api extends HttpClient {
     };
     taxes = {
         /**
-         * @description This endpoint creates a new tax representing a customizable tax rate applicable to either the organization or a specific customer.
+         * @description This endpoint creates a new tax representing a customizable tax rate applicable to either a billing entity or a specific customer.
          *
          * @tags taxes
          * @name CreateTax
@@ -3472,7 +3472,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint retrieves all existing taxes representing a customizable tax rate applicable to either the organization or a specific customer.
+         * @description This endpoint retrieves all existing taxes representing a customizable tax rate applicable to either a billing entity or a specific customer.
          *
          * @tags taxes
          * @name FindAllTaxes
@@ -3489,7 +3489,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint updates an existing tax representing a customizable tax rate applicable to either the organization or a specific customer.
+         * @description This endpoint updates an existing tax representing a customizable tax rate applicable to either a billing entity or a specific customer.
          *
          * @tags taxes
          * @name UpdateTax
@@ -3507,11 +3507,11 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint retrieves an existing tax representing a customizable tax rate applicable to either the organization or a specific customer. The tax is identified by its unique code.
+         * @description This endpoint retrieves an existing tax representing a customizable tax rate applicable to either a billing entity or a specific customer. The tax is identified by its unique code.
          *
          * @tags taxes
          * @name FindTax
-         * @summary Retrieve a Tax
+         * @summary Retrieve a tax
          * @request GET:/taxes/{code}
          * @secure
          */
@@ -3731,7 +3731,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint is used to retrieve a specific wallet transactions.
+         * @description This endpoint is used to retrieve a specific wallet transaction.
          *
          * @tags wallets
          * @name FindWalletTransaction
@@ -3799,7 +3799,7 @@ class Api extends HttpClient {
     };
     webhooks = {
         /**
-         * @description This endpoint is used to retrieve the public key used to verify the webhooks signature
+         * @description **Deprecated.** Use `GET /webhooks/json_public_key` instead. This endpoint is used to retrieve the public key used to verify the webhook signature.
          *
          * @tags webhooks
          * @name FetchPublicKey
@@ -3816,7 +3816,7 @@ class Api extends HttpClient {
             ...params,
         }),
         /**
-         * @description This endpoint is used to retrieve the public key used to verify the webhooks signature, wrapped in a JSON object. Prefer this endpoint over the deprecated GET /webhooks/public_key.
+         * @description This endpoint is used to retrieve the public key used to verify the webhook signature, wrapped in a JSON object. Prefer this endpoint over the deprecated `GET /webhooks/public_key`.
          *
          * @tags webhooks
          * @name FetchJsonPublicKey
@@ -3838,7 +3838,7 @@ class Api extends HttpClient {
          *
          * @tags webhook_endpoints
          * @name CreateWebhookEndpoint
-         * @summary Create a webhook_endpoint
+         * @summary Create a webhook endpoint
          * @request POST:/webhook_endpoints
          * @secure
          */