# Lago

## Docs

- [The add-on object](https://getlago.com/docs/api-reference/add-ons/add-on-object): This object represents an add-on, a one-time fee that can be applied on one-off invoices.
- [Create an add-on](https://getlago.com/docs/api-reference/add-ons/create): This endpoint is used to create an add-on that can be then attached to a one-off invoice.
- [Delete an add-on](https://getlago.com/docs/api-reference/add-ons/destroy): This endpoint is used to delete an existing add-on.
- [List all add-ons](https://getlago.com/docs/api-reference/add-ons/get-all): This endpoint is used to list all existing add-ons.
- [Retrieve an add-on](https://getlago.com/docs/api-reference/add-ons/get-specific): This endpoint is used to retrieve a specific add-on.
- [Update an add-on](https://getlago.com/docs/api-reference/add-ons/update): This endpoint is used to update an existing add-on.
- [Retrieve gross revenue](https://getlago.com/docs/api-reference/analytics/gross-revenue): 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.
- [Retrieve invoice collection](https://getlago.com/docs/api-reference/analytics/invoice-collection): 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`.
- [Retrieve invoiced usage](https://getlago.com/docs/api-reference/analytics/invoiced-usage): 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.
- [Retrieve MRR (monthly recurring revenue)](https://getlago.com/docs/api-reference/analytics/mrr): This endpoint is used to list MRR.
- [Retrieve overdue balance](https://getlago.com/docs/api-reference/analytics/overdue-balance): Overdue balance is the total amount associated with overdue invoices (invoices with pending or failed payments which are past their due dates).
- [Create a billable metric](https://getlago.com/docs/api-reference/billable-metrics/create): This endpoint creates a new billable metric representing a pricing component of your application.
- [Delete a billable metric](https://getlago.com/docs/api-reference/billable-metrics/destroy): This endpoint deletes an existing billable metric representing a pricing component of your application.
- [List all billable metrics](https://getlago.com/docs/api-reference/billable-metrics/get-all): This endpoint retrieves all existing billable metrics that represent pricing components of your application.
- [List all billable metric groups](https://getlago.com/docs/api-reference/billable-metrics/get-all-groups)
- [Retrieve a billable metric](https://getlago.com/docs/api-reference/billable-metrics/get-specific): This endpoint retrieves an existing billable metric that represents a pricing component of your application. The billable metric is identified by its unique code.
- [The billable metric object](https://getlago.com/docs/api-reference/billable-metrics/object): This object represents a billable metric used to define how incoming events are aggregated in order to measure consumption.
- [Update a billable metric](https://getlago.com/docs/api-reference/billable-metrics/update): This endpoint updates an existing billable metric representing a pricing component of your application.
- [The applied coupon object](https://getlago.com/docs/api-reference/coupons/applied-coupon-object): This object represents a coupon applied to a customer. It can override the initial values of a coupon.
- [Apply a coupon](https://getlago.com/docs/api-reference/coupons/apply): This endpoint is used to apply a specific coupon to a customer, before or during a subscription.
- [The coupon object](https://getlago.com/docs/api-reference/coupons/coupon-object): This object represents a coupon used to applies discount on customer next invoices. This coupon can be applied to a customer with overriden values.
- [Create a coupon](https://getlago.com/docs/api-reference/coupons/create): This endpoint is used to create a coupon that can be then attached to a customer to create a discount.
- [Delete a coupon](https://getlago.com/docs/api-reference/coupons/destroy): This endpoint is used to delete a coupon.
- [Delete an applied coupon](https://getlago.com/docs/api-reference/coupons/destroy-applied-coupon): This endpoint is used to delete a specific coupon that has been applied to a customer.
- [List all coupons](https://getlago.com/docs/api-reference/coupons/get-all): This endpoint is used to list all existing coupons.
- [List all applied coupons](https://getlago.com/docs/api-reference/coupons/get-all-applied): This endpoint is used to list all applied coupons. You can filter by coupon status and by customer.
- [Retrieve a coupon](https://getlago.com/docs/api-reference/coupons/get-specific): This endpoint is used to retrieve a specific coupon.
- [Update a coupon](https://getlago.com/docs/api-reference/coupons/update): This endpoint is used to update a coupon that can be then attached to a customer to create a discount.
- [Create a credit note](https://getlago.com/docs/api-reference/credit-notes/create): This endpoint creates a new credit note.
- [The credit note object](https://getlago.com/docs/api-reference/credit-notes/credit-note-object): This object represents a credit note, used to refund or credit back a customer for a fee or an invoice.
- [Download a credit note](https://getlago.com/docs/api-reference/credit-notes/download): This endpoint downloads the PDF of an existing credit note.
- [List all credit notes](https://getlago.com/docs/api-reference/credit-notes/get-all): This endpoint list all existing credit notes.
- [Retrieve a credit note](https://getlago.com/docs/api-reference/credit-notes/get-specific): This endpoint retrieves an existing credit note.
- [Update a credit note](https://getlago.com/docs/api-reference/credit-notes/update): This endpoint updates an existing credit note.
- [Void available credit](https://getlago.com/docs/api-reference/credit-notes/void): This endpoint voids the available credit linked to a specific credit note.
- [The customer usage object](https://getlago.com/docs/api-reference/customer-usage/customer-usage-object): This object represents the usage-based charges associated with one of your customers for a defined billing period. It allows you to monitor customer usage throughout the period.
- [Retrieve current usage](https://getlago.com/docs/api-reference/customer-usage/get-current): Retrieve real-time customer usage data for the current open billing period.
- [Retrieve past usage](https://getlago.com/docs/api-reference/customer-usage/get-past): Fetch historical customer usage data for closed billing periods.
- [Create a customer](https://getlago.com/docs/api-reference/customers/create): This endpoint creates a new customer.
- [Retrieve customer portal URL](https://getlago.com/docs/api-reference/customers/customer-portal): 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
- [Delete a customer](https://getlago.com/docs/api-reference/customers/delete): This endpoint deletes an existing customer.
- [List all customers](https://getlago.com/docs/api-reference/customers/get-all): This endpoint retrieves all existing customers.
- [Retrieve a customer](https://getlago.com/docs/api-reference/customers/get-specific): This endpoint retrieves an existing customer.
- [The customer object](https://getlago.com/docs/api-reference/customers/object): This object represents a customer of your business. It lets you create or update a customer, but also track usage and create invoices for the same customer.
- [Regenerate checkout URL](https://getlago.com/docs/api-reference/customers/psp-checkout-url): This endpoint regenerates the Payment Provider Checkout URL of a Customer.
- [Update a customer](https://getlago.com/docs/api-reference/customers/update): This endpoint creates a new customer.
- [Batch usage events](https://getlago.com/docs/api-reference/events/batch): This endpoint can be used to send a batch of usage records. Each request may include up to 100 events.
- [Estimate an upcoming fee](https://getlago.com/docs/api-reference/events/estimated-fee): Estimate the fees that would be created after reception of an event for a billable metric attached to one or multiple pay in advance charges.
- [The event object](https://getlago.com/docs/api-reference/events/event-object): Events represents usage measurement sent to lago application that will then be aggregated into invoice line items.
- [Retrieve an event](https://getlago.com/docs/api-reference/events/get-specific): This endpoint is used for retrieving a specific usage measurement event that has been sent to a customer or a subscription.
- [List all events](https://getlago.com/docs/api-reference/events/list-events): This endpoint is used for retrieving all events.
- [Send usage event](https://getlago.com/docs/api-reference/events/usage): This endpoint is used for transmitting usage measurement events to either a designated customer or a specific subscription.
- [Delete a fee](https://getlago.com/docs/api-reference/fees/destroy-fee): This endpoint is used for deleting a specific fee that has not yet been invoiced
- [The fee object](https://getlago.com/docs/api-reference/fees/fee-object): This object represents a line item of an invoice, handling amount, billed units and item description.
- [List all fees](https://getlago.com/docs/api-reference/fees/list-fees): This endpoint is used for retrieving all fees that has been issued.
- [Retrieve a fee](https://getlago.com/docs/api-reference/fees/retrieve-fee): This endpoint is used for retrieving a specific fee that has been issued.
- [Update a fee](https://getlago.com/docs/api-reference/fees/update-fee): This endpoint is used for updating a specific fee that has been issued.
- [Getting started](https://getlago.com/docs/api-reference/intro): Lago API allows your application to push customer information and metrics (events) from your application to the billing application.
- [Create a one-off invoice](https://getlago.com/docs/api-reference/invoices/create-oneoff): This endpoint is used for issuing a one-off invoice.
- [Download an invoice](https://getlago.com/docs/api-reference/invoices/download): This endpoint is used for downloading a specific invoice PDF document.
- [Finalize an invoice](https://getlago.com/docs/api-reference/invoices/finalize): This endpoint is used for finalizing a draft invoice.
- [List all invoices](https://getlago.com/docs/api-reference/invoices/get-all): This endpoint is used for retrieving all invoices.
- [Retrieve an invoice](https://getlago.com/docs/api-reference/invoices/get-specific): This endpoint is used for retrieving a specific invoice that has been issued.
- [The invoice object](https://getlago.com/docs/api-reference/invoices/invoice-object): This object represents an invoice generated by Lago for a specific customer. This invoice summarizes the fees generated by a subscription, usage-based charges, prepaid credit purchases, or one-off invoices.
- [Generate a payment URL](https://getlago.com/docs/api-reference/invoices/payment-url): This endpoint generates a checkout link for a specific invoice.
- [Refresh an invoice](https://getlago.com/docs/api-reference/invoices/refresh): This endpoint is used for refreshing a draft invoice.
- [Retry an invoice payment](https://getlago.com/docs/api-reference/invoices/retry): This endpoint resends an invoice for collection and retry a payment.
- [Retry an invoice finalization](https://getlago.com/docs/api-reference/invoices/retry_finalization): This endpoint is used for retrying to generate a failed invoice.
- [Update an invoice](https://getlago.com/docs/api-reference/invoices/update): This endpoint is used for updating an existing invoice.
- [Void an invoice](https://getlago.com/docs/api-reference/invoices/void): This endpoint is used for voiding an invoice. You can void an invoice only when it's in a `finalized` status, and the payment status is not `succeeded`.
- [The organization object](https://getlago.com/docs/api-reference/organizations/organization-object): This object represents your organization. You can define all invoicing details and settings within it.
- [Update your organization](https://getlago.com/docs/api-reference/organizations/update): This endpoint is used to update your own organization's settings.
- [Create a payment request](https://getlago.com/docs/api-reference/payment-requests/create): This endpoint is used to create a payment request to collect payments of overdue invoices of a given customer
- [List all payment requests](https://getlago.com/docs/api-reference/payment-requests/get-all): This endpoint is used to list all existing payment requests.
- [The payment request object](https://getlago.com/docs/api-reference/payment-requests/payment-request-object): This object represents payment request of a group of overdue invoices for which a payment intent can be created, to settle the overdue balance.
- [Create a plan](https://getlago.com/docs/api-reference/plans/create): This endpoint creates a plan with subscription and usage-based charges. It supports flexible billing cadence (in-advance or in-arrears) and allows for both recurring and metered charges.
- [Delete a plan](https://getlago.com/docs/api-reference/plans/destroy): This endpoint deletes a specific plan. Note that this plan could be associated with active subscriptions.
- [List all plans](https://getlago.com/docs/api-reference/plans/get-all-plans): This endpoint retrieves all existing plans.
- [Retrieve a plan](https://getlago.com/docs/api-reference/plans/get-specific): This endpoint retrieves a specific plan.
- [The plan object](https://getlago.com/docs/api-reference/plans/object): This object represents a plan. This plan can then be assigned to a customer.
- [Update a plan](https://getlago.com/docs/api-reference/plans/update): This endpoint updates a specific plan with subscription and usage-based charges. It supports flexible billing cadence (in-advance or in-arrears) and allows for both recurring and metered charges.
- [Currencies](https://getlago.com/docs/api-reference/resources/currencies): List of accepted currencies (ISO 4217).
- [Document locales](https://getlago.com/docs/api-reference/resources/locales)
- [Timezones](https://getlago.com/docs/api-reference/resources/timezones): List of accepted timezones (TZ database).
- [Create a subscription](https://getlago.com/docs/api-reference/subscriptions/assign-plan): This endpoint assigns a plan to a customer, creating or modifying a subscription. Ideal for initial subscriptions or plan changes (upgrades/downgrades).
- [List all subscriptions](https://getlago.com/docs/api-reference/subscriptions/get-all): This endpoint retrieves all active subscriptions.
- [Retrieve subscription lifetime usage](https://getlago.com/docs/api-reference/subscriptions/get-lifetime-usage): This endpoint allows you to retrieve the total lifetime usage of a subscription.
- [Retrieve a subscription](https://getlago.com/docs/api-reference/subscriptions/get-specific): This endpoint retrieves a specific subscription.
- [The lifetime usage object](https://getlago.com/docs/api-reference/subscriptions/lifetime-usage-object): This object represents the total lifetime usage of a subscription, particularly useful for progressive billing.
- [The subscription object](https://getlago.com/docs/api-reference/subscriptions/subscription-object): This object represents the assignation of plan to one of the customer of your business.
- [Terminate a subscription](https://getlago.com/docs/api-reference/subscriptions/terminate): This endpoint allows you to terminate a subscription.
- [Update a subscription](https://getlago.com/docs/api-reference/subscriptions/update): This endpoint allows you to update a subscription.
- [Update subscription lifetime usage](https://getlago.com/docs/api-reference/subscriptions/update-lifetime-usage): This endpoint allows you to update the total lifetime usage of a subscription for migration purposes.
- [Create a tax rate](https://getlago.com/docs/api-reference/taxes/create): This endpoint creates a new tax representing a customizable tax rate applicable to either the organization or a specific customer.
- [Delete a tax rate](https://getlago.com/docs/api-reference/taxes/destroy): This endpoint is used to delete a tax.
- [List all tax rates](https://getlago.com/docs/api-reference/taxes/get-all): This endpoint retrieves all existing taxes representing a customizable tax rate applicable to either the organization or a specific customer.
- [Retrieve a tax rate](https://getlago.com/docs/api-reference/taxes/get-specific): 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.
- [The tax object](https://getlago.com/docs/api-reference/taxes/tax-object): This object represents a customizable tax rate applicable to either the organization or a specific customer.
- [Update a tax rate](https://getlago.com/docs/api-reference/taxes/update): This endpoint updates an existing tax representing a customizable tax rate applicable to either the organization or a specific customer.
- [Create a wallet](https://getlago.com/docs/api-reference/wallets/create): This endpoint is used to create a wallet with prepaid credits.
- [List all wallets](https://getlago.com/docs/api-reference/wallets/get-all): This endpoint is used to list all wallets with prepaid credits.
- [List all wallet transactions](https://getlago.com/docs/api-reference/wallets/get-all-transactions): This endpoint is used to list all wallet transactions.
- [Retrieve a wallet](https://getlago.com/docs/api-reference/wallets/get-specific): This endpoint is used to retrieve an existing wallet with prepaid credits.
- [Terminate a wallet](https://getlago.com/docs/api-reference/wallets/terminate): This endpoint is used to terminate an existing wallet with prepaid credits.
- [Top-up a wallet](https://getlago.com/docs/api-reference/wallets/top-up): This endpoint is used to top-up an active wallet.
- [Update a wallet](https://getlago.com/docs/api-reference/wallets/update): This endpoint is used to update an existing wallet with prepaid credits.
- [The wallet object](https://getlago.com/docs/api-reference/wallets/wallet-object): This object represents a wallet, holding free or prepaid credits. 
- [The wallet transaction object](https://getlago.com/docs/api-reference/wallets/wallet-transaction-object): This object represents a wallet transaction. It is used for topping up or voiding prepaid credits.
- [Create a webhook endpoint](https://getlago.com/docs/api-reference/webhook-endpoints/create): This endpoint is used to create a webhook endpoint.
- [Delete a webhook endpoint](https://getlago.com/docs/api-reference/webhook-endpoints/destroy)
- [Retrieve a webhook endpoint](https://getlago.com/docs/api-reference/webhook-endpoints/get-all): This endpoint is used to list all webhook endpoints.
- [List all webhook endpoints](https://getlago.com/docs/api-reference/webhook-endpoints/get-specific): This endpoint is used to retrieve an existing webhook endpoint.
- [Update a webhook endpoint](https://getlago.com/docs/api-reference/webhook-endpoints/update): This endpoint is used to update an existing webhook endpoint.
- [The webhook endpoint object](https://getlago.com/docs/api-reference/webhook-endpoints/webhook-endpoint-object): This object represents the webhook endpoint used for listening to Lago’s events
- [Format & Signature](https://getlago.com/docs/api-reference/webhooks/format---signature): Webhooks are HTTP notifications sent from Lago to your application.
- [Messages](https://getlago.com/docs/api-reference/webhooks/messages): Below is a list of the event types we currently send. Please note that additional event types may be introduced in the future, so your code should be flexible enough to accommodate new types as they arise. Our objective is to maintain a consistent and predictable event structure, making it easier to integrate and handle messages, along with the objects they affect.
- [Product updates](https://getlago.com/docs/changelog/product): New updates and improvements to Lago.
- [About Lago](https://getlago.com/docs/faq/about-lago)
- [About the software](https://getlago.com/docs/faq/about-software)
- [Community](https://getlago.com/docs/faq/community)
- [Deployment](https://getlago.com/docs/faq/deployment)
- [General](https://getlago.com/docs/faq/general)
- [Pricing](https://getlago.com/docs/faq/pricing)
- [Product features](https://getlago.com/docs/faq/product-features)
- [Gross revenue](https://getlago.com/docs/guide/analytics/gross-revenue)
- [Invoice collection](https://getlago.com/docs/guide/analytics/invoice-collection)
- [Overdue invoices](https://getlago.com/docs/guide/analytics/invoice-overdue)
- [Monthly Recurring Revenue (MRR)](https://getlago.com/docs/guide/analytics/mrr)
- [Overview](https://getlago.com/docs/guide/analytics/overview)
- [Aggregation examples](https://getlago.com/docs/guide/billable-metrics/aggregation-types/aggregation-examples)
- [COUNT](https://getlago.com/docs/guide/billable-metrics/aggregation-types/count)
- [UNIQUE COUNT](https://getlago.com/docs/guide/billable-metrics/aggregation-types/count-unique)
- [CUSTOM](https://getlago.com/docs/guide/billable-metrics/aggregation-types/custom-agg)
- [LATEST](https://getlago.com/docs/guide/billable-metrics/aggregation-types/latest)
- [MAX](https://getlago.com/docs/guide/billable-metrics/aggregation-types/max)
- [Overview](https://getlago.com/docs/guide/billable-metrics/aggregation-types/overview): Aggregation types will define how consumption will be measured.
- [SUM](https://getlago.com/docs/guide/billable-metrics/aggregation-types/sum)
- [WEIGHTED SUM](https://getlago.com/docs/guide/billable-metrics/aggregation-types/weighted-sum)
- [Create billable metrics](https://getlago.com/docs/guide/billable-metrics/create-billable-metrics): Billable metrics define how incoming events are aggregated in order to measure consumption.
- [Delete billable metrics](https://getlago.com/docs/guide/billable-metrics/delete-billable-metrics)
- [Filters](https://getlago.com/docs/guide/billable-metrics/filters): When setting up your pricing, you may want to filters events according to their property. To do so, you can create filters for your billable metric.
- [Recurring vs metered](https://getlago.com/docs/guide/billable-metrics/recurring-vs-metered)
- [Rounding](https://getlago.com/docs/guide/billable-metrics/rounding): Lago aggregates your events in real time. You can add rounding rules to the final result.
- [SQL Expressions](https://getlago.com/docs/guide/billable-metrics/sql-expressions): For more advanced calculations, you can use SQL custom expressions. These expressions are helpful when the aggregation results for a billable metric require complex calculations.
- [Coupons](https://getlago.com/docs/guide/coupons): Coupons allow you to offer discounts to your customers. When you apply a coupon to a customer,  its value will be deducted from their next subscription invoice(s).
- [Credit notes](https://getlago.com/docs/guide/credit-notes)
- [Customer management](https://getlago.com/docs/guide/customers/customer-management)
- [Customer metadata](https://getlago.com/docs/guide/customers/customer-metadata)
- [The customer portal](https://getlago.com/docs/guide/customers/customer-portal)
- [Invoice a customer](https://getlago.com/docs/guide/customers/invoice-customer)
- [Automatic dunning](https://getlago.com/docs/guide/dunning/automatic-dunning): Automate how to communicate with your customers to remind them of overdue invoices and attempt to recover their overdue balance using dunning campaigns.
- [Manual dunning](https://getlago.com/docs/guide/dunning/manual-dunning): Dunning refers to the process of communicating with customers to remind them of overdue invoices and attempt to recover the outstanding amounts.
- [Emails](https://getlago.com/docs/guide/emails): Send automatic emails when issuing an invoice or any billing documents.
- [Entitlements](https://getlago.com/docs/guide/entitlements)
- [Events list](https://getlago.com/docs/guide/events/events-list): By ingesting events, you can see them flowing in the Lago application by using the events list. It allows you to take a deeper look at ingested events and detect possible warnings.
- [Ingesting usage](https://getlago.com/docs/guide/events/ingesting-usage): This guide explains how Lago ingests usage-based events coming from your application.
- [Metering ingestion sources](https://getlago.com/docs/guide/events/metering-source): Here is a list of sources you can use to ingest usage data. Some of these sources are capable of handling up to 15,000 events per second with default settings.
- [Retrieving usage](https://getlago.com/docs/guide/events/retrieve-usage): Learn how to retrieve usage data for both current and past billing periods.
- [Integration testing](https://getlago.com/docs/guide/integration-testing): This step-by-step integration guide will help you get started with Lago.
- [Welcome to Lago](https://getlago.com/docs/guide/introduction/welcome-to-lago): Lago is an open-source software for metering and usage-based billing. It's the best alternative to Chargebee, Recurly or Stripe Billing for companies that need to handle complex billing logic.
- [Why billing is a nightmare](https://getlago.com/docs/guide/introduction/why-billing-is-a-nightmare)
- [Download invoices](https://getlago.com/docs/guide/invoicing/download-invoices)
- [Export invoices](https://getlago.com/docs/guide/invoicing/export): Lago enables you to filter invoices and export them as a simple or advanced CSV file, tailored to your needs.
- [Fees](https://getlago.com/docs/guide/invoicing/fees): A fee is a line item in an invoice.
- [Grace period](https://getlago.com/docs/guide/invoicing/grace-period)
- [Invoice metadata](https://getlago.com/docs/guide/invoicing/invoice-metadata)
- [Net payment term](https://getlago.com/docs/guide/invoicing/net-payment-term)
- [Overview](https://getlago.com/docs/guide/invoicing/overview): Lago automatically generates invoices for each customer according to the plan model.
- [Taxes](https://getlago.com/docs/guide/invoicing/taxes): When generating invoices, you may need to apply vat or other taxes. By creating taxes and applying them to the organization or/and customers,  their invoices will be directly affected.
- [Void invoices](https://getlago.com/docs/guide/invoicing/void)
- [Lago Cloud](https://getlago.com/docs/guide/lago-cloud): Lago Cloud is the fully hosted version of our open-source billing API.
- [Lago OpenAPI](https://getlago.com/docs/guide/lago-open-api)
- [Migration to v1.2.0](https://getlago.com/docs/guide/migration/migration-to-v1.2.0)
- [Create add-ons](https://getlago.com/docs/guide/one-off-invoices/create-add-ons): Add-ons are a useful feature that allows you to add a fixed charge that is not recurring to one-off invoices.  This can be used to apply one-time fees such as a setup fee, one-time payment, or customer success fee.
- [Issue one-off invoices](https://getlago.com/docs/guide/one-off-invoices/create-one-off-invoices): One-off invoices allow you to bill immediately one or several add-ons to a customer.  This guide will show you how to create a one-off invoice for a specific customer using the add-ons.
- [Adyen integration](https://getlago.com/docs/guide/payments/adyen-integration): Lago's native integration with Adyen allows you to collect payments automatically when new invoices are generated.
- [GoCardless integration](https://getlago.com/docs/guide/payments/gocardless-integration): Lago's native integration with GoCardless allows you to collect payments via direct debit.
- [Overview](https://getlago.com/docs/guide/payments/overview): Connect Lago to any payment providers by using native integrations or webhook messages.
- [Payment retries](https://getlago.com/docs/guide/payments/payment-retries)
- [Stripe integration](https://getlago.com/docs/guide/payments/stripe-integration): Lago's native integration with Stripe allows you to collect payments automatically when new invoices are generated.
- [Arrears vs Advance](https://getlago.com/docs/guide/plans/charges/arrears-vs-advance): Usage-based charges can be either charged in advance or in arrears
- [Custom price](https://getlago.com/docs/guide/plans/charges/charge-models/custom-price)
- [Dynamic](https://getlago.com/docs/guide/plans/charges/charge-models/dynamic)
- [Graduated](https://getlago.com/docs/guide/plans/charges/charge-models/graduated)
- [Graduated percentage](https://getlago.com/docs/guide/plans/charges/charge-models/graduated-percentage)
- [Package](https://getlago.com/docs/guide/plans/charges/charge-models/package)
- [Percentage](https://getlago.com/docs/guide/plans/charges/charge-models/percentage)
- [Standard](https://getlago.com/docs/guide/plans/charges/charge-models/standard)
- [Volume](https://getlago.com/docs/guide/plans/charges/charge-models/volume)
- [Charges with filters](https://getlago.com/docs/guide/plans/charges/charges-with-filters): Charge your customers by leveraging a combination of filters specified in the billable metric.
- [Invoiceable vs Uninvoiceable](https://getlago.com/docs/guide/plans/charges/invoiceable-vs-noninvoiceable): In-advance charges can be either invoiceable or not.
- [Metered vs Recurring](https://getlago.com/docs/guide/plans/charges/metered-vs-recurring): Usage-based charges can be either metered or recurring
- [Overview](https://getlago.com/docs/guide/plans/charges/overview): In addition to the price of the plan, you can charge your customers for usage.
- [Prorated vs Full](https://getlago.com/docs/guide/plans/charges/prorated-vs-full): Usage-based charges can be either bill fully or prorated based on the number of days used.
- [Spending minimums](https://getlago.com/docs/guide/plans/charges/spending-minimum)
- [Commitments](https://getlago.com/docs/guide/plans/commitment)
- [Overview](https://getlago.com/docs/guide/plans/overview): If Billable metrics are made to measure customer usage, Plans are made to apply prices to this usage.
- [Plan model](https://getlago.com/docs/guide/plans/plan-model): The plan model defines when and how much a customer is charged.
- [Progressive billing](https://getlago.com/docs/guide/plans/progressive-billing): Progressive billing, also known as threshold billing, automatically triggers an invoice when a customer's cumulative usage reaches predefined thresholds. This method ensures that customers cannot exceed certain usage limits without ensuring payment is received, reducing the risk of unpaid services or fraud.
- [API Keys](https://getlago.com/docs/guide/security/api-keys)
- [RBAC - Role Base Access Control](https://getlago.com/docs/guide/security/rbac): Define user roles & permissions in Lago.
- [SOC 2 Type 2](https://getlago.com/docs/guide/security/soc): Keeping your data secure.
- [Single Sign-On (SSO)](https://getlago.com/docs/guide/security/sso)
- [Useful commands](https://getlago.com/docs/guide/self-hosted/commands): Useful commands for self-hosted users.
- [Docker](https://getlago.com/docs/guide/self-hosted/docker): Docker is the easiest way to get started with the self-hosted version of Lago.
- [Overview](https://getlago.com/docs/guide/self-hosted/overview): Deploy Lago seamlessly on your infrastructure, compatible with both free and premium editions.
- [Tracking & Analytics](https://getlago.com/docs/guide/self-hosted/tracking-analytics)
- [Versions update](https://getlago.com/docs/guide/self-hosted/update-instance)
- [Assign a plan to a customer](https://getlago.com/docs/guide/subscriptions/assign-plan): A subscription is created when a plan is assigned to a customer.  You can assign a plan to a customer at any time (i.e. when the customer record is created or later on).
- [Edit a subscription](https://getlago.com/docs/guide/subscriptions/edit-subscription): You can edit a subscription at any time, whether it's active or pending.
- [Terminate a subscription](https://getlago.com/docs/guide/subscriptions/terminate-subscription): You can terminate a subscription at any time, whether it's active or pending.
- [Upgrades and downgrades](https://getlago.com/docs/guide/subscriptions/upgrades-downgrades): Customers have the flexibility to easily upgrade or downgrade their plan at any given moment.
- [Overview](https://getlago.com/docs/guide/wallet-and-prepaid-credits/overview): Since usage-based charges can be calculated at the end of the billing period, you often need to wait to collect payments. With prepaid credits, you can now unlock recurring revenue opportunities for pay-as-you-go pricing models.
- [Top-up and void credits](https://getlago.com/docs/guide/wallet-and-prepaid-credits/wallet-top-up-and-void): Add and void credits, to the customer's wallet.
- [Webhooks](https://getlago.com/docs/guide/webhooks)
- [NetSuite](https://getlago.com/docs/integrations/accounting/netsuite): Lago seamlessly integrates with NetSuite, enabling real-time synchronization of billing data with your preferred accounting tool.
- [Xero](https://getlago.com/docs/integrations/accounting/xero): Lago seamlessly integrates with Xero, enabling real-time synchronization of billing data with your preferred accounting tool.
- [N8N](https://getlago.com/docs/integrations/alerting/n8n)
- [Zapier](https://getlago.com/docs/integrations/alerting/zapier)
- [HubSpot](https://getlago.com/docs/integrations/crm/hubspot): Lago syncs billing data to HubSpot in real-time.
- [Salesforce CPQ](https://getlago.com/docs/integrations/crm/salesforce-cpq): Lago syncs billing data to Salesforce in real-time.
- [Salesforce CRM](https://getlago.com/docs/integrations/crm/salesforce-crm): Lago syncs billing data to Salesforce in real-time.
- [Airbyte (ETL)](https://getlago.com/docs/integrations/data/airbyte)
- [Oso](https://getlago.com/docs/integrations/entitlements/osohq)
- [Introduction](https://getlago.com/docs/integrations/introduction): Find all Lago native integrations with third party tools, whether it's related to payment providers, alerting systems or data integrations.
- [AWS Marketplace](https://getlago.com/docs/integrations/marketplaces/aws-marketplace): Lago integrates with AWS marketplace through our partner Suger.io
- [Azure Marketplace](https://getlago.com/docs/integrations/marketplaces/azure-marketplace): Lago integrates with Azure marketplace through our partner Suger.io
- [GCP Marketplace](https://getlago.com/docs/integrations/marketplaces/gcp-marketplace): Lago integrates with GCP marketplace through our partner Suger.io
- [Adyen](https://getlago.com/docs/integrations/payments/adyen-integration): Lago's native integration with Adyen allows you to collect payments automatically when new invoices are generated.
- [GoCardless](https://getlago.com/docs/integrations/payments/gocardless-integration): Lago's native integration with GoCardless allows you to collect payments via direct debit.
- [Stripe](https://getlago.com/docs/integrations/payments/stripe-integration): Lago's native integration with Stripe allows you to collect payments automatically when new invoices are generated.
- [Anrok](https://getlago.com/docs/integrations/taxes/anrok): Lago's native integration with Anrok allows you to automatically update your invoices with tax amounts sourced directly from Anrok. This integration ensures compliance with international tax regulations by calculating taxes for US & non-US obligations, like VAT.
- [Lago EU Taxes](https://getlago.com/docs/integrations/taxes/lago-eu-taxes)
- [Hightouch](https://getlago.com/docs/integrations/usage/hightouch): Hightouch is a Data Activation platform that syncs data from sources (database, warehouses, spreadsheet and much more) to business  applications and developer tools. This data can be sent to Lago, our usage-based billing platform, to automate your billing process  and ensure accurate invoicing for your customers.
- [Segment](https://getlago.com/docs/integrations/usage/segment): Segment is a powerful tool that allows you to track the usage of your customers, providing valuable insights that can help you make  data-driven decisions. This data can be sent to Lago, our usage-based billing platform, to automate your billing process and ensure  accurate invoicing for your customers.
- [Clone Segment pricing](https://getlago.com/docs/templates/hybrid/segment): Replicate Segment's hybrid pricing model with Lago.
- [Introduction](https://getlago.com/docs/templates/introduction): Replicate these popular B2B pricing templates to kickstart your journey with Lago.
- [Clone Algolia pricing](https://getlago.com/docs/templates/payg/algolia): Replicate Algolia's pay-as-you-go pricing model with Lago.
- [Clone Google BigQuery pricing](https://getlago.com/docs/templates/payg/bigquery): Replicate BigQuery's pay-as-you-go pricing model and offer free upfront credits with Lago.
- [Clone Notion pricing](https://getlago.com/docs/templates/per-seat/notion): Replicate Notion's per-seat pricing model with Lago.
- [Clone Mistral pricing](https://getlago.com/docs/templates/per-token/mistral): Replicate Mistral's per-token pricing model with Lago.
- [Clone OpenAI pricing](https://getlago.com/docs/templates/per-token/openai): Replicate OpenAI's per-token pricing model with Lago.
- [Clone Stripe pricing](https://getlago.com/docs/templates/per-transaction/stripe): Replicate Stripe's per-transaction pricing model with Lago.


## Optional

- [Blog](https://www.getlago.com/blog)
- [Community](https://www.getlago.com/slack)
- [GitHub](https://github.com/getlago/lago)
- [Status](https://status.getlago.com/)


# The add-on object

This object represents an add-on, a one-time fee that can be applied on one-off invoices.



# Create an add-on

POST /add_ons
This endpoint is used to create an add-on that can be then attached to a one-off invoice.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/add_ons" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "add_on": {
        "name": "Setup Fee",
        "code": "setup_fee",
        "amount_cents": 50000,
        "amount_currency": "USD",
        "description": "Implementation fee for new customers.",
        "tax_codes": ["french_reduced_vat"]
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import AddOn

  client = Client(api_key='__YOUR_API_KEY__')

  add_on = AddOn(
    name='Setup Fee',
    code='setup_fee',
    amount_cents=50000,
    amount_currency='USD',
    description='Implementation fee for new customers.',
    tax_codes= ['french_standard_vat']
  )

  try:
      client.add_ons.create(add_on)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  add_on = {
    name: 'Setup Fee',
    code: 'setup_fee',
    description: 'Implementation fee for new customers.',
    amount_cents: 50000,
    amount_currency: 'USD',
    tax_codes: ['french_standard_vat']
  }

  client.add_ons.create(add_on)
  ```

  ```js Javascript
  const addOnObject = {
    name: "Setup Fee",
    code: "setup_fee",
    description: "Implementation fee for new customers.",
    amount_cents: 50000,
    amount_currency: "USD",
    tax_codes: ["french_standard_vat"],
  };

  await client.addOns.createAddOn({ addOn: addOnObject });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  addOnInput := &lago.AddOnInput{
          Name:           "Setup Fee",
          Code:           "setup_fee",
          AmountCents:    50000,
          AmountCurrency: lago.USD,
          Description:    "Implementation fee for new customers.",
  }

  addOn, err := lagoClient.AddOn().Create(addOnInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // addOn is *lago.AddOn
  fmt.Println(addOn)
  }
  ```
</RequestExample>


# Delete an add-on

DELETE /add_ons/{code}
This endpoint is used to delete an existing add-on.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request DELETE "$LAGO_URL/api/v1/add_ons/:code" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.add_ons.destroy('code')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.add_ons.destroy('code')
  ```

  ```js Javascript
  await client.addOns.destroyAddOn('code')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

    addOn, err := lagoClient.AddOn().Delete("__YOUR_ADDON_CODE__")
    if err != nil {
      // Error is *lago.Error
      panic(err)
    }

    // addOn is *lago.AddOn
    fmt.Println(addOn)
  }
  ```
</RequestExample>


# List all add-ons

GET /add_ons
This endpoint is used to list all existing add-ons.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/add_ons?per_page=2&page=1" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.add_ons.find_all({'per_page': 2, 'page': 1})
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.add_ons.get_all({ per_page: 2, page: 3 })
  ```

  ```js Javascript
  await client.addOns.findAllAddOns({ per_page: 2, page: 3 });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  addOnListInput := &lago.AddOnListInput{
      PerPage: 1,
      Page: 1,
  }

  addOnResult, err := lagoClient.AddOn().GetList(addOnListInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // addOnResult is *lago.AddOnResult
  fmt.Println(addOnResult)
  }
  ```
</RequestExample>


# Retrieve an add-on

GET /add_ons/{code}
This endpoint is used to retrieve a specific add-on.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/add_ons/:code" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.add_ons.find('code')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.add_ons.get('code')
  ```

  ```js Javascript
  await client.addOns.findAddOn("code");
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  addOn, err := lagoClient.AddOn().Get("__YOUR_ADDON_CODE__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // addOn is *lago.AddOn
  fmt.Println(addOn)
  }
  ```
</RequestExample>


# Update an add-on

PUT /add_ons/{code}
This endpoint is used to update an existing add-on.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request PUT "$LAGO_URL/api/v1/add_ons/:code" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "add_on": {
        "name": "Setup Fee",
        "code": "setup_fee",
        "amount_cents": 50000,
        "amount_currency": "USD",
        "description": "Implementation fee for new customers."
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import AddOn

  client = Client(api_key='__YOUR_API_KEY__')

  update_params = AddOn(name='Setup Fee')

  try:
      client.add_ons.update(update_params, 'setup_fee')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  update_params = {name: 'Setup Fee'}
  client.add_ons.update(update_params, 'setup_fee')
  ```

  ```js Javascript
  await client.addOns.updateAddOn("code", {
    add_on: { name: "Setup Fee", code: "setup_fee" },
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  addOnInput := &lago.AddOnInput{
          Name:           "Setup Fee",
          Code:           "setup_fee",
          AmountCents:    50000,
          AmountCurrency: lago.USD,
          Description:    "Implementation fee for new customers.",
  }

  addOn, err := lagoClient.AddOn().Update(addOnInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // addOn is *lago.AddOn
  fmt.Println(addOn)
  }
  ```
</RequestExample>


# Retrieve gross revenue

GET /analytics/gross_revenue
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.



# Retrieve invoice collection

GET /analytics/invoice_collection
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`.



# Retrieve invoiced usage

GET /analytics/invoiced_usage
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.



# Retrieve MRR (monthly recurring revenue)

GET /analytics/mrr
This endpoint is used to list MRR.



# Retrieve overdue balance

GET /analytics/overdue_balance
Overdue balance is the total amount associated with overdue invoices (invoices with pending or failed payments which are past their due dates).



# Create a billable metric

POST /billable_metrics
This endpoint creates a new billable metric representing a pricing component of your application.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "billable_metric": {
      "name": "Storage",
      "code": "storage",
      "description": "GB of storage used in my application",
      "aggregation_type": "sum_agg",
      "recurring": false,
      "field_name": "gb",
      "weighted_interval": "seconds",
      "filters": [
        {
          "key": "region",
          "values": ["us-east-1", "us-east-2", "eu-west-1"]
        }
      ]
    }
  }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import BillableMetricFilter, BillableMetric

  client = Client(api_key='__YOUR_API_KEY__')

  filter = BillableMetricFilter(
    key='region',
    values=['us-east-1', 'us-east-2', 'eu-west-1']
  )

  billable_metric = BillableMetric(
  name='Storage',
  code='storage',
  recurring=false,
  description='GB of storage used in my application',
  aggregation_type='sum_agg',
  field_name='gb',
  weighted_interval= 'seconds',
  filters=[filter]
  )
  try:
      client.billable_metrics.create(billable_metric)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.billable_metrics.create({
    name: 'Storage',
    code: 'storage',
    description: 'GB of storage used in my application',
    aggregation_type: 'sum_agg',
    recurring: false,
    field_name: 'gb',
    weighted_interval: 'seconds',
    filters: [
      {
        key: 'region',
        values: %w[us-east-1 us-east-2 eu-west-1]
      }
    ]
  })
  ```

  ```js Javascript
  await client.billableMetrics.createBillableMetric({
    billable_metric: {
      name: "Storage",
      code: "storage",
      aggregation_type: "sum_agg",
      recurring: false,
      field_name: "gb",
      weighted_interval: "seconds",
      filters: [
        {
          key: "region",
          values: ["us-east-1", "us-east-2", "eu-west-1"],
        }
      ]
    },
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

    bmInput := &lago.BillableMetricInput{
      Name:            "Storage",
      Code:            "storage",
      Description:     "GB of storage used in my application"
      AggregationType: lago.SumAggregation,
      FieldName:       "gb",
      WeightedInterval:"seconds",
      Recurring:       false,
      Filters: [1]map[string]interface{}{
          "key": "region",
          "values": [3]string{"us-east-1", "us-east-2", "eu-west-1"},
      },
    }

    billableMetric, err := lagoClient.BillableMetric().Create(bmInput)
    if err != nil {
      // Error is *lago.Error
      panic(err)
    }

    // billableMetric is *lago.BillableMetric
    fmt.Println(billableMetric)
  }
  ```
</RequestExample>


# Delete a billable metric

DELETE /billable_metrics/{code}
This endpoint deletes an existing billable metric representing a pricing component of your application.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request DELETE "$LAGO_URL/api/v1/billable_metrics/:code" \
  --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.billable_metrics.destroy('code')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.billable_metrics.destroy('code')
  ```

  ```js Javascript
  await client.billableMetrics.destroyBillableMetric('code')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
      lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

      billableMetric, err := lagoClient.BillableMetric().Delete("__YOUR_BILLABLE_METRIC_CODE__")
      if err != nil {
      // Error is *lago.Error
      panic(err)
      }

      // billableMetric is *lago.BillableMetric
      fmt.Println(billableMetric)
  }
  ```
</RequestExample>


# List all billable metrics

GET /billable_metrics
This endpoint retrieves all existing billable metrics that represent pricing components of your application.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/billable_metrics?per_page=2&page=1" \
  --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.billable_metrics.find_all({'per_page': 2, 'page': 1})
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.billable_metrics.get_all({ per_page: 2, page: 3 })
  ```

  ```js Javascript
  await client.billableMetrics.findAllBillableMetrics({ per_page: 2, page: 3 });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
      lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

      bmListInput := &lago.BillableMetricListInput{
      PerPage: 10,
      Page: 1,
      }

      billableMetricResult, err := lagoClient.BillableMetric().GetList(bmListInput)
      if err != nil {
      // Error is *lago.Error
      panic(err)
      }

      // billableMetric is *lago.BillableMetricResult
      fmt.Println(billableMetricResult)
  }
  ```
</RequestExample>


# List all billable metric groups

GET /billable_metrics/{code}/groups

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/billable_metrics/:code/groups?per_page=2&page=1" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.groups.find_all('billable_metric_code', {'per_page': 2, 'page': 1})
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.groups.get_all('billable_metric_code', { per_page: 2, page: 3 })
  ```

  ```js Javascript
  await client.billableMetrics.findAllBillableMetricGroups(
    "billable_metric_code",
    { per_page: 2, page: 3 }
  );
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  groupListInput := &lago.GroupListInput{
      Code: "billable_metric_code",
      PerPage: 10,
      Page: 1,
  }

  groupResult, err := lagoClient.Group().GetList(groupListInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // group is *lago.GroupResult
  fmt.Println(groupResult)
  }
  ```
</RequestExample>


# Retrieve a billable metric

GET /billable_metrics/{code}
This endpoint retrieves an existing billable metric that represents a pricing component of your application. The billable metric is identified by its unique code.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/billable_metrics/:code" \
  --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.billable_metrics.find('code')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.billable_metrics.get('code')
  ```

  ```js Javascript
  await client.billableMetrics.findBillableMetric('code');
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  billableMetric, err := lagoClient.BillableMetric().Get("__BILLABLE_METRIC_CODE__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // billableMetric is *lago.BillableMetric
  fmt.Println(billableMetric)
  }
  ```
</RequestExample>


# The billable metric object

This object represents a billable metric used to define how incoming events are aggregated in order to measure consumption.



# Update a billable metric

PUT /billable_metrics/{code}
This endpoint updates an existing billable metric representing a pricing component of your application.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request PUT "$LAGO_URL/api/v1/billable_metrics/:code" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "billable_metric": {
        "name": "Storage",
        "code": "storage",
        "description": "GB of storage used in my application",
        "aggregation_type": "sum_agg",
        "recurring": false,
        "field_name": "gb",
        "weighted_interval": "seconds",
        "filters": [
          {
            "key": "provider",
            "values": ["us-east-1", "us-east-2", "eu-west-1"]
          }
        ]
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import BillableMetricFilter, BillableMetric

  client = Client(api_key='__YOUR_API_KEY__')

  filter = BillableMetricFilter(
    key='region',
    values=['us-east-1', 'us-east-2', 'eu-west-1']
  )

  billable_metric = BillableMetric(
    name='Storage',
    code='storage',
    description='GB of storage used in my application',
    aggregation_type='sum_agg',
    recurring=false,
    field_name='gb',
    weighted_interval= 'seconds',
    filters=[filter]
  )

  try:
      client.billable_metrics.update(billable_metric, 'code')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.billable_metrics.update({
    name: 'Storage',
    code: 'storage',
    description: 'GB of storage used in my application',
    aggregation_type: 'sum_agg',
    recurring: false,
    field_name: 'gb',
    weighted_interval: 'seconds',
    filters: [
      {
        key: 'region',
        values: %w[us-east-1 us-east-2 eu-west-1]
      }
    ]
  }, 'code')
  ```

  ```js Javascript
  const newBillableMetricObject = {
    name: "Storage",
    code: "storage",
    recurring: false,
    aggregation_type: "sum_agg",
    weighted_interval: "seconds",
    field_name: "gb",
  };

  await client.billableMetrics.updateBillableMetric("code", {
    billableMetric: newBillableMetricObject,
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

    bmInput := &lago.BillableMetricInput{
      Name:            "Storage",
      Code:            "storage",
      Description:     "GB of storage used in my application"
      AggregationType: lago.SumAggregation,
      FieldName:       "gb",
      Recurring:       false,
      WeightedInterval: "seconds",
      Filters: [1]map[string]interface{}{
          "key": "region",
          "values": [3]string{"us-east-1", "us-east-2", "eu-west-1"},
      },
    }

    billableMetric, err := lagoClient.BillableMetric().Update(bmInput)
    if err != nil {
      // Error is *lago.Error
      panic(err)
    }

    // billableMetric is *lago.BillableMetric
    fmt.Println(billableMetric)
  }
  ```
</RequestExample>


# The applied coupon object

This object represents a coupon applied to a customer. It can override the initial values of a coupon.

<RequestExample>
  ```json The applied coupon object
  {
    "applied_coupon": {
      "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "lago_coupon_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "coupon_code": "startup_deal",
      "coupon_name": "Startup Deal",
      "lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
      "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "status": "active",
      "amount_cents": 2000,
      "amount_cents_remaining": 50,
      "amount_currency": "EUR",
      "percentage_rate": "string",
      "frequency": "recurring",
      "frequency_duration": 3,
      "frequency_duration_remaining": 1,
      "expiration_at": "2022-04-29T08:59:51Z",
      "created_at": "2022-04-29T08:59:51Z",
      "terminated_at": "2022-04-29T08:59:51Z"
    }
  }
  ```
</RequestExample>

## Attributes

<ResponseField name="applied_coupon" type="object">
  <Expandable title="object" defaultOpen="true">
    <ResponseField name="lago_id" type="string" required>
      Unique identifier of the applied coupon, created by Lago.
    </ResponseField>

    <ResponseField name="lago_coupon_id" type="string" required>
      Unique identifier of the coupon, created by Lago.
    </ResponseField>

    <ResponseField name="coupon_name" type="string" required>
      The name of the coupon.
    </ResponseField>

    <ResponseField name="coupon_code" type="string" required>
      Unique code used to identify the coupon.
    </ResponseField>

    <ResponseField name="external_customer_id" type="string" required>
      The customer external unique identifier (provided by your own application)
    </ResponseField>

    <ResponseField name="lago_customer_id" type="string" required>
      Unique identifier of the customer, created by Lago.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      The status of the coupon. Can be either `active` or `terminated`.
    </ResponseField>

    <ResponseField name="amount_cents" type="integer">
      The amount of the coupon in cents. This field is required only for coupon with `fixed_amount` type.
    </ResponseField>

    <ResponseField name="amount_cents_remaining" type="integer">
      The remaining amount in cents for a `fixed_amount` coupon with a frequency set to `once`.
      This field indicates the remaining balance or value that can still be utilized from the coupon.
    </ResponseField>

    <ResponseField name="amount_currency" type="string">
      The currency of the coupon. This field is required only for coupon with `fixed_amount` type.
    </ResponseField>

    <ResponseField name="expiration_at" type="string">
      The expiration date and time of the coupon. This field is required only for coupons with `expiration` set to `time_limit`.
      The expiration date and time should be specified in UTC format according to the ISO 8601 datetime standard.
      It indicates the exact moment when the coupon will expire and is no longer valid.
    </ResponseField>

    <ResponseField name="frequency" type="string" required>
      The type of frequency for the coupon. It can have three possible values: `once`, `recurring`, or `forever`.

      *   If set to `once`, the coupon is applicable only for a single use.
      *   If set to `recurring`, the coupon can be used multiple times for recurring billing periods.
      *   If set to `forever`, the coupon has unlimited usage and can be applied indefinitely.
    </ResponseField>

    <ResponseField name="frequency_duration" type="string">
      Specifies the number of billing periods to which the coupon applies. This field is required only for coupons
      with a `recurring` frequency type
    </ResponseField>

    <ResponseField name="frequency_duration_remaining" type="integer">
      The remaining number of billing periods to which the coupon is applicable. This field determines the remaining
      usage or availability of the coupon based on the remaining billing periods.
    </ResponseField>

    <ResponseField name="percentage_rate" type="float">
      The percentage rate of the coupon. This field is required only for coupons with a `percentage` coupon type.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      The date and time when the coupon was assigned to a customer. It is expressed in UTC format according to the ISO 8601 datetime standard.
    </ResponseField>

    <ResponseField name="terminated_at" type="string">
      This field indicates the specific moment when the coupon amount is fully utilized or when the coupon is removed from the customer's coupon list. It is expressed in UTC format according to the ISO 8601 datetime standard.
    </ResponseField>
  </Expandable>
</ResponseField>


# Apply a coupon

POST /applied_coupons
This endpoint is used to apply a specific coupon to a customer, before or during a subscription.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/applied_coupons" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "applied_coupon": {
        "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
        "coupon_code": "startup_deal",
        "amount_cents": 2500,
        "amount_currency": "EUR",
        "frequency": "recurring",
        "frequency_duration": 3
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import AppliedCoupon

  client = Client(api_key='__YOUR_API_KEY__')

  applied_coupon = AppliedCoupon(
    external_customer_id="5eb02857-a71e-4ea2-bcf9-57d8885990ba",
    coupon_code="startup_deal",
    amount_cents=2500,
    amount_currency="EUR",
    frequency="recurring",
    frequency_duration=3
  )

  try:
      client.applied_coupons.create(applied_coupon)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.applied_coupons.create(
    external_customer_id: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    coupon_code: "startup_deal",
    amount_cents: 2500,
    amount_currency: "EUR",
    frequency: "recurring",
    frequency_duration: 3
  )
  ```

  ```js Javascript
  const appliedCouponObject = {
    external_customer_id: "5eb02857-a71e-4ea2-bcf9-57d8885990ba",
    coupon_code: "startup_deal",
    amount_cents: 2500,
    amount_currency: "EUR",
    frequency: "recurring" as AppliedCouponObject["frequency"],
    frequency_duration: 3,
  };

  await client.appliedCoupons.applyCoupon({
    appliedCoupon: appliedCouponObject,
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  applyCouponInput := &lago.ApplyCouponInput{
      ExternalCustomerID: "5eb02857-a71e-4ea2-bcf9-57d8885990ba",
      CouponCode: "startup_deal",
      Frequency: lago.CouponFrequencyRecurring,
      FrequencyDuration: 3
  }

  appliedCoupon, err := lagoClient.Coupon().ApplyToCustomer(applyCouponInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // appliedCoupon is *lago.AppliedCoupon
  fmt.Println(appliedCoupon)
  }
  ```
</RequestExample>


# The coupon object

This object represents a coupon used to applies discount on customer next invoices. This coupon can be applied to a customer with overriden values.



# Create a coupon

POST /coupons
This endpoint is used to create a coupon that can be then attached to a customer to create a discount.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/coupons" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "coupon": {
        "name": "Startup Deal",
        "code": "startup_deal",
        "amount_cents": 5000,
        "amount_currency": "USD",
        "coupon_type": "fixed_amount",
        "reusable": true,
        "frequency": "recurring",
        "frequency_duration": 6,
        "expiration": "time_limit",
        "expiration_at": "2022-08-08T23:59:59Z",
        "applies_to": {
          "plan_codes": ["startup_plan"],
          "billable_metric_codes": []
        }
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import Coupon

  client = Client(api_key='__YOUR_API_KEY__')

  coupon = Coupon(
    name='Startup Deal',
    code='startup_deal',
    amount_cents=5000,
    amount_currency='USD',
    coupon_type='fixed_amount',
    frequency='recurring',
    frequency_duration=6,
    reusable=True
    expiration='time_limit',
    expiration_at='2022-08-08T23:59:59Z',
    applies_to=LimitationConfiguration(plan_codes=['startup_plan'])
  )

  try:
      client.coupons.create(coupon)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  coupon = {
    name: 'Startup Deal',
    code: 'startup_deal',
    expiration: 'time_limit',
    expiration_at: '2022-08-08T23:59:59Z',
    amount_cents: 5000,
    amount_currency: 'USD',
    coupon_type: 'fixed_amount',
    reusable: true,
    frequency: 'recurring',
    frequency_duration: 6,
    applies_to: {
      plan_codes: ['startup_plan']
    }
  }

  client.coupons.create(coupon)
  ```

  ```js Javascript
  const couponObject = {
    name: "Startup Deal",
    code: "startup_deal",
    expiration: "time_limit" as CouponObject["expiration"],
    expiration_at: "2022-08-08T23:59:59Z",
    amount_cents: 5000,
    amount_currency: "USD",
    coupon_type: "fixed_amount" as CouponObject["couponType"],
    reusable: true,
    frequency: "recurring" as CouponObject["frequency"],
    frequency_duration: 6,
    applies_to: {
      plan_codes: ["startup_plan"],
    },
  };

  await client.coupons.createCoupon({ coupon: couponObject });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  limitationInput := &lago.LimitationInput{
      PlanCodes:        []string{"startup_plan"}
  }

  couponInput := &lago.CouponInput{
      Name:               "Startup Deal",
      Code:               "startup_deal",
      AmountCents:        5000,
      AmountCurrency:     lago.USD,
      Reusable:           true,
      Expiration:         lago.CouponExpirationTimeLimit,
      ExpirationAt:       "2022-08-08T23:59:59Z",
      CouponType:         lago.CouponTypeFixedAmount,
      Frequency:          lago.CouponFrequencyRecurring,
      FrequencyDuration:  6,
      AppliesTo           limitationInput
  }

  coupon, err := lagoClient.Coupon().Create(couponInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // coupon is *lago.Coupon
  fmt.Println(coupon)
  }
  ```
</RequestExample>


# Delete a coupon

DELETE /coupons/{code}
This endpoint is used to delete a coupon.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request DELETE "$LAGO_URL/api/v1/coupons/:code" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.coupons.destroy('code')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.coupons.destroy('code')
  ```

  ```js Javascript
  await client.coupons.destroyCoupon('code');
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  coupon, err := lagoClient.Coupon().Delete("__YOUR_COUPON_CODE__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // coupon is *lago.Coupon
  fmt.Println(coupon)
  }
  ```
</RequestExample>


# Delete an applied coupon

DELETE /customers/{external_customer_id}/applied_coupons/{applied_coupon_id}
This endpoint is used to delete a specific coupon that has been applied to a customer.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request DELETE "$LAGO_URL/api/v1/customers/:external_customer_id/applied_coupons/:applied_coupon_id" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.applied_coupons.destroy('external_customer_id', 'applied_coupon_id')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.applied_coupons.destroy('external_customer_id', 'applied_coupon_id')
  ```

  ```js Javascript
  await client.customers.deleteAppliedCoupon(
    "external_customer_id",
    "applied_coupon_id"
  );
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  appliedCoupon, err := lagoClient.Coupon().AppliedCouponDelete('external_customer_id', 'applied_coupon_id')
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // appliedCoupon is *lago.AppliedCoupon
  fmt.Println(appliedCoupon)
  }
  ```
</RequestExample>


# List all coupons

GET /coupons
This endpoint is used to list all existing coupons.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/coupons?per_page=2&page=1" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.coupons.find_all({'per_page': 2, 'page': 1})
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.coupons.get_all({ per_page: 2, page: 3 })
  ```

  ```js Javascript
  await client.coupons.findAllCoupons({ per_page: 2, page: 3 });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  couponListInput := &lago.CouponListInput{
      PerPage: 1,
      Page: 1,
  }

  couponResult, err := lagoClient.Coupon().GetList(couponListInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // couponResult is *lago.CouponResult
  fmt.Println(couponResult)
  }
  ```
</RequestExample>


# List all applied coupons

GET /applied_coupons
This endpoint is used to list all applied coupons. You can filter by coupon status and by customer.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/applied_coupons?per_page=2&page=1" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.applied_coupons.find_all({'per_page': 2, 'page': 1})
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.applied_coupons.get_all({ per_page: 2, page: 3 })
  ```

  ```js Javascript
  await client.appliedCoupons.findAllAppliedCoupons({ per_page: 2, page: 3 });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  couponListInput := &lago.AppliedCouponListInput{
      PerPage: 1,
      Page: 1,
  }

  couponResult, err := lagoClient.AppliedCoupon().GetList(couponListInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // couponResult is *lago.CouponResult
  fmt.Println(couponResult)
  }
  ```
</RequestExample>


# Retrieve a coupon

GET /coupons/{code}
This endpoint is used to retrieve a specific coupon.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/coupons/:code" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.coupons.find('code')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.coupons.get('code')
  ```

  ```js Javascript
  await client.coupons.findCoupon('code')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  coupon, err := lagoClient.Coupon().Get("__YOUR_COUPON_CODE__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // coupon is *lago.Coupon
  fmt.Println(coupon)
  }
  ```
</RequestExample>


# Update a coupon

PUT /coupons/{code}
This endpoint is used to update a coupon that can be then attached to a customer to create a discount.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request PUT "$LAGO_URL/api/v1/coupons/:code" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "coupon": {
        "name": "Startup Deal",
        "code": "startup_deal",
        "amount_cents": 5000,
        "amount_currency": "USD",
        "coupon_type": "fixed_amount",
        "frequency": "recurring",
        "frequency_duration": 6,
        "reusable": true,
        "expiration": "time_limit",
        "expiration_at": "2022-08-08T23:59:59Z"
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import Coupon

  client = Client(api_key='__YOUR_API_KEY__')

  update_params = Coupon(name='new name')

  try:
      client.coupons.update(update_params, 'code')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  update_params = {name: 'new name'}
  client.coupons.update(update_params, 'code_bm')
  ```

  ```js Javascript
  await client.coupons.updateCoupon("code", { coupon: { name: "new name" } });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  couponInput := &lago.CouponInput{
      Name:               "Coupon",
          Code:               "coupon",
          AmountCents:        1500,
          AmountCurrency:     lago.EUR,
          Expiration:         lago.CouponExpirationTimeLimit,
          ExpirationAt:       "2022-08-08T23:59:59Z",
  }

  coupon := lagoClient.Coupon().Update(couponInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // coupon is *lago.Coupon
  fmt.Println(coupon)
  }
  ```
</RequestExample>


# Create a credit note

POST /credit_notes
This endpoint creates a new credit note.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/credit_notes" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "credit_note": {
        "invoice_id": "__LAGO_INVOICE_ID__",
        "reason": "duplicated_charge",
        "credit_amount_cents": 10,
        "refund_amount_cents": 5,
        "items": [
          {
            "fee_id": "__LAGO_FEE_ID__",
            "amount_cents": 10
          },
          {
            "fee_id": "__LAGO_FEE_ID__",
            "amount_cents": 5
          }
        ]
      }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models.credit_note import Item, Items, CreditNote

  client = Client(api_key='__YOUR_API_KEY__')

  item1 = Item(
    fee_id="__LAGO_FEE_ID__",
    amount_cents=10
  )

  item2 = Item(
    fee="__LAGO_FEE_ID__",
    amount_cents=5,
  )

  credit_note = CreditNote(
    lago_id="__LAGO_INVOICE_ID__",
    reason="other",
    credit_amount_cents=10,
    refund_amount_cents=5,
    items= Items(__root__=[item1, item2])
  )

  try:
      client.credit_notes.create(credit_note)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  credit_note = {
    invoice_id: '__LAGO_INVOICE_ID__',
    reason: 'duplicated_charge',
    credit_amount_cents: 10,
    refund_amount_cents: 5,
    items: [
      {
        fee_id: '__LAGO_FEE_ID__',
        amount_cents: 10
      },
      {
        fee_id: '__LAGO_FEE_ID__',
        amount_cents: 5
      }
    ]
  }

  client.credit_notes.create(credit_note)
  ```

  ```js Javascript
  import { CreditNoteObject } from "lago-javascript-client";

  const creditNoteObject = {
    invoice_id: "__LAGO_INVOICE_ID__",
    reason: "other" as CreditNoteObject["reason"],
    credit_amount_cents: 10,
    refund_amount_cents: 5,
    items: [
      {
        fee_id: "__LAGO_FEE_ID__",
        amount_cents: 10,
      },
      {
        fee_id: "__LAGO_FEE_ID__",
        amount_cents: 5,
      },
    ],
  };

  await client.creditNotes.createCreditNote({ creditNote: creditNoteObject });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

    creditNoteInput := &lago.CreditNoteInput{
      LagoInvoiceID: "__LAGO_INVOICE_ID__",
      Reason:        lago.CreditNoteReasonDuplicatedCharge,
      CreditAmountCents 10,
      RefundAmountCents 5,
      Items:         []lago.CreditNoteItemInput{
        {
          LagoFeeID         "__LAGO_FEE_ID__",
          AmountCents 10,
        },
        {
          LagoFeeID         "__LAGO_FEE_ID__",
          AmountCents 5,
        },
      },
    }

    creditNote, err := lagoClient.CreditNote().Create(creditNoteInput)
    if err != nil {
      // Error is *lago.Error
      panic(err)
    }

    fmt.Println(creditNote)
  }
  ```
</RequestExample>


# The credit note object

This object represents a credit note, used to refund or credit back a customer for a fee or an invoice.



# Download a credit note

POST /credit_notes/{lago_id}/download
This endpoint downloads the PDF of an existing credit note.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  CREDIT_NOTE_ID="__CREDIT_NOTE_ID__"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/credit_notes/$CREDIT_NOTE_ID/download" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  invoice = None
  try:
      invoice = client.credit_notes.download('__CREDIT_NOTE_ID__')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.credit_notes.download('__CREDIT_NOTE_ID__')
  ```

  ```js Javascript
  await client.creditNotes.downloadCreditNote('credit-note-id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

  credit_note, err := lagoClient.CreditNote().Download("__CREDIT_NOTE_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // credit_note is *lago.CreditNote
  fmt.Println(credit_note)

  // If the credit note has to be generated, the response is empty
  // And you will get a webhook `credit_note.generated`
  }
  ```
</RequestExample>


# List all credit notes

GET /credit_notes
This endpoint list all existing credit notes.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/credit_notes?per_page=2&page=1" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.credit_notes.find_all({'per_page': 2, 'page': 1})
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.credit_notes.get_all({ per_page: 2, page: 3 })
  ```

  ```js Javascript
  await client.creditNotes.findAllCreditNotes({ per_page: 2, page: 3 });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

  creditNoteListInput := &lago.CreditNoteListInput{
      PerPage: 1,
      Page: 1,
      ExternalCustomerID: "cus_1234",
  }

  creditNoteResult, err := lagoClient.CreditNote().GetList(creditNoteListInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // creditNoteResult is *lago.CreditNoteResult
  fmt.Println(creditNoteResult)
  }
  ```
</RequestExample>


# Retrieve a credit note

GET /credit_notes/{lago_id}
This endpoint retrieves an existing credit note.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  CREDIT_NOTE_ID="__CREDIT_NOTE_ID__"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/credit_notes/$CREDIT_NOTE_ID" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.credit_notes.find('__CREDIT_NOTE_ID__')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.credit_notes.get('__CREDIT_NOTE_ID__')
  ```

  ```js Javascript
  await client.creditNotes.findCreditNote('credit-note-id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

  creditNote, err := lagoClient.CreditNotes().Get("__CREDIT_NOTE_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // credit note is *lago.CreditNote
  fmt.Println(creditNote)
  }
  ```
</RequestExample>


# Update a credit note

PUT /credit_notes/{lago_id}
This endpoint updates an existing credit note.



# Void available credit

PUT /credit_notes/{lago_id}/void
This endpoint voids the available credit linked to a specific credit note.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  CREDIT_NOTE_ID="__CREDIT_NOTE_ID__"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request PUT "$LAGO_URL/api/v1/credit_notes/$CREDIT_NOTE_ID/void" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  try:
      client.credit_notes.void("__CREDIT_NOTE_ID__")
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.credit_note.void('__CREDIT_NOTE_ID__')
  ```

  ```js Javascript
  await client.creditNotes.voidCreditNote('credit-node-id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

  creditNote, err := lagoClient.CreditNote().Void("__CREDIT_NOTE_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // creditNote is *lago.CreditNote
  fmt.Println(creditNote)
  }
  ```
</RequestExample>


# The customer usage object

This object represents the usage-based charges associated with one of your customers for a defined billing period. It allows you to monitor customer usage throughout the period.



# Retrieve current usage

GET /customers/{external_customer_id}/current_usage
Retrieve real-time customer usage data for the current open billing period.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"
  EXTERNAL_CUSTOMER_ID="__EXTERNAL_CUSTOMER_ID__"
  EXTERNAL_SUBSCRIPTION_ID="__EXTERNAL_SUBSCRIPTION_ID__"

  curl --location --request GET "$LAGO_URL/api/v1/customers/$EXTERNAL_CUSTOMER_ID/current_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  customer_usage = None
  try:
      customer_usage = client.customers.current_usage('external_customer_id', 'external_subscription_id')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')
  customer_usage = client.customer.current_usage(
    'external_customer_id', 'external_subscription_id'
  )
  ```

  ```js Javascript
  await client.customers.findCustomerCurrentUsage(
    "customer_external_id",
    { external_subscription_id: "external_subscription_id" }
  );
  ```

  ```go Go
    import "fmt"
    import "github.com/getlago/lago-go-client"

    func main() {
      lagoClient := lago.New().
        SetApiKey("__YOUR_API_KEY__")

      customerUsage, err := lagoClient.Customer().CurrentUsage("__YOUR_CUSTOMER_ID__")
      if err != nil {
        // Error is *lago.Error
        panic(err)
      }

      // customerUsage is *lago.CustomerUsage
      fmt.Println(customerUsage)
    }
  ```
</RequestExample>


# Retrieve past usage

GET /customers/{external_customer_id}/past_usage
Fetch historical customer usage data for closed billing periods.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"
  EXTERNAL_CUSTOMER_ID="__EXTERNAL_CUSTOMER_ID__"
  EXTERNAL_SUBSCRIPTION_ID="__EXTERNAL_SUBSCRIPTION_ID__"

  curl --location --request GET "$LAGO_URL/api/v1/customers/$EXTERNAL_CUSTOMER_ID/past_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  customer_usage = None
  try:
      customer_usage = client.customers.past_usage('external_customer_id', 'external_subscription_id')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')
  customer_usage = client.customer.past_usage(
    'external_customer_id', 'external_subscription_id'
  )
  ```

  ```js Javascript
  await client.customers.findCustomerPastUsage(
    "customer_external_id",
    { external_subscription_id: "external_subscription_id" }
  );
  ```

  ```go Go
    import "fmt"
    import "github.com/getlago/lago-go-client"

    func main() {
      lagoClient := lago.New().
        SetApiKey("__YOUR_API_KEY__")

      customerUsage, err := lagoClient.Customer().PastUsage("__YOUR_CUSTOMER_ID__")
      if err != nil {
        // Error is *lago.Error
        panic(err)
      }

      // customerUsage is *lago.CustomerUsage
      fmt.Println(customerUsage)
    }
  ```
</RequestExample>


# Create a customer

POST /customers
This endpoint creates a new customer.

<Warning>
  This endpoint performs an upsert operation.
</Warning>

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/customers" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "customer": {
        "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
        "address_line1": "5230 Penfield Ave",
        "address_line2": "",
        "city": "Woodland Hills",
        "country": "US",
        "currency": "USD",
        "email": "dinesh@piedpiper.test",
        "legal_name": "Coleman-Blair",
        "legal_number": "49-008-2965",
        "tax_identification_number": "EU123456789",
        "logo_url": "http://hooli.com/logo.png",
        "name": "Gavin Belson",
        "phone": "1-171-883-3711 x245",
        "state": "CA",
        "timezone": "Europe/Paris",
        "url": "http://hooli.com",
        "zipcode": "91364",
        "billing_configuration": {
          "invoice_grace_period": 3,
          "payment_provider": "stripe",
          "provider_customer_id": "cus_12345",
          "sync": true,
          "sync_with_provider": true,
          "document_locale": "fr",
          "provider_payment_methods": ["card", "sepa_debit", "us_bank_account", "bacs_debit", "link"]
        },
        "metadata": [
          {
            "key": "Purchase Order",
            "value": "123456789",
            "display_in_invoice": true
          }
        ],
        "tax_codes": ["french_standard_vat"]
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import Customer, CustomerBillingConfiguration

  client = Client(api_key='__YOUR_API_KEY__')

  metadata_object = Metadata(
    display_in_invoice=True,
    key='Purchase Order',
    value='123456789'
  )

  customer = Customer(
    external_id="5eb02857-a71e-4ea2-bcf9-57d8885990ba",
    address_line1="5230 Penfield Ave",
    address_line2=None,
    city="Woodland Hills",
    currency="USD",
    country="US",
    email="test@example.com",
    legal_name="Coleman-Blair",
    legal_number="49-008-2965",
    tax_identification_number="EU123456789",
    logo_url="http://hooli.com/logo.png",
    name="Test Name",
    phone="1-171-883-3711 x245",
    state="CA",
    timezone="Europe/Paris",
    url="http://hooli.com",
    zipcode="91364",
    billing_configuration=CustomerBillingConfiguration(
      invoice_grace_period=3,
      payment_provider="stripe",
      provider_customer_id="cus_12345",
      sync=true,
      sync_with_provider=true,
      document_locale="fr"
    ),
    metadata=MetadataList(__root__=[metadata_object])
  )

  try:
      client.customers.create(customer)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.customers.create(
    external_id: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    address_line1: "5230 Penfield Ave",
    address_line2: nil,
    city: "Woodland Hills",
    country: "US",
    currency: "USD",
    email: "dinesh@piedpiper.test",
    legal_name: "Coleman-Blair",
    legal_number: "49-008-2965",
    tax_identification_number: "EU123456789",
    logo_url: "http://hooli.com/logo.png",
    name: "Gavin Belson",
    phone: "1-171-883-3711 x245",
    state: "CA",
    timezone: "Europe/Paris",
    url: "http://hooli.com",
    zipcode: "91364",
    billing_configuration: {
      invoice_grace_period: 3,
      payment_provider: "stripe",
      provider_customer_id: "cus_12345",
      sync: true,
      sync_with_provider: true,
      document_locale: "fr",
      provider_payment_methods: ["card", "sepa_debit", "us_bank_account", "bacs_debit", "link"]
    },
    metadata: [
      {
        key: 'Purchase Order',
        value: '123456789',
        display_in_invoice: true
      }
    ],
    tax_codes: ["french_standard_vat"]
  )
  ```

  ```js Javascript
  import { BillingConfigurationCustomer } from "lago-javascript-client";

  const customerObject = {
    external_id: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    address_line1: "5230 Penfield Ave",
    city: "Woodland Hills",
    currency: "EUR",
    country: "US",
    email: "dinesh@piedpiper.test",
    legal_name: "Coleman-Blair",
    legal_number: "49-008-2965",
    tax_identification_number: "EU123456789",
    logo_url: "http://hooli.com/logo.png",
    name: "Gavin Belson",
    phone: "1-171-883-3711 x245",
    state: "CA",
    timezone: "Europe/Paris",
    url: "http://hooli.com",
    zipcode: "91364",
    billing_configuration: {
      invoice_grace_period: 3,
      paymentProvider:
        "stripe" as BillingConfigurationCustomer["paymentProvider"],
      provider_customer_id: "cus_12345",
      sync: true,
      sync_with_provider: true,
      document_locale: "fr"
    },
    metadata: [
      {
        key: "Purchase Order",
        value: "123456789",
        display_in_invoice: true,
      },
    ],
  };

  await client.customers.createCustomer({ customer: customerObject });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  customerInput := &lago.CustomerInput{
      ExternalID:              "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      Name:                    "Gavin Belson",
      Email:                   "dinesh@piedpiper.test",
      AddressLine1:            "5230 Penfield Ave",
      AddressLine2:            "",
      City:                    "Woodland Hills",
      Country:                 "US",
      Currency:                "USD",
      State:                   "CA",
      Zipcode:                 "75001",
      LegalName:               "Coleman-Blair",
      LegalNumber:             "49-008-2965",
      TaxIdentificationNumber: "EU123456789",
      Phone:                   "+330100000000",
      Timezone:                "Europe/Paris",
      URL:                     "http://hooli.com",
      BillingConfiguration: &CustomerBillingConfigurationInput{
      InvoiceGracePeriod: 3,
      PaymentProvider: lago.PaymentProviderStripe,
      ProviderCustomerID: "cus_123456789",
      SyncWithProvider: true,
      DocumentLocale: "fr"
      },
      Metadata: [
      &CustomerMetadataInput{
          Key: "Purchase Order",
          Value: "123456789",
          DisplayInInvoice: true
      }
      ]
  }

  customer, err := lagoClient.Customer().Create(customerInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // You can use the same input to update the customer
  customer, err := lagoClient.Customer().Update(customerInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // customer is *lago.Customer
  fmt.Println(customer)
  }
  ```
</RequestExample>


# Retrieve customer portal URL

GET /customers/{external_customer_id}/portal_url
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

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/customers/:external_id/portal_url" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
    client.customers.portal_url('external_id')
  except LagoApiError as e:
    repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.customers.portal_url('external_id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  customer, err := lagoClient.Customer().PortalUrl("__EXTERNAL_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // customer is *lago.Customer
  fmt.Println(customer)
  }
  ```
</RequestExample>


# Delete a customer

DELETE /customers/{external_id}
This endpoint deletes an existing customer.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request DELETE "$LAGO_URL/api/v1/customers/:external_id" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.customers.destroy('external_id')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.customers.destroy('external_id')
  ```

  ```js Javascript
  await client.customers.deleteCustomer('external_id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  customer, err := lagoClient.Customer().Delete("external_id")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // customer is *lago.Customer
  fmt.Println(customer)
  }
  ```
</RequestExample>


# List all customers

GET /customers
This endpoint retrieves all existing customers.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/customers?per_page=2&page=1" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.customers.find_all({'per_page': 2, 'page': 1})
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.customers.get_all({ per_page: 2, page: 3 })
  ```

  ```js Javascript
  await client.customers.findAllCustomers({ per_page: 2, page: 3 });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  customerListInput := &lago.CustomerListInput{
      PerPage: 1,
      Page: 1,
  }

  customerResult, err := lagoClient.Customer().GetList(customerListInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // customerResult is *lago.CustomerResult
  fmt.Println(customerResult)
  }
  ```
</RequestExample>


# Retrieve a customer

GET /customers/{external_id}
This endpoint retrieves an existing customer.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/customers/:external_id" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.customers.find('external_id')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.customers.get('external_id')
  ```

  ```js Javascript
  await client.customers.findCustomer('external_id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  customer, err := lagoClient.Customer().Get("__EXTERNAL_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // customer is *lago.Customer
  fmt.Println(customer)
  }
  ```
</RequestExample>


# The customer object

This object represents a customer of your business. It lets you create or update a customer, but also track usage and create invoices for the same customer.



# Regenerate checkout URL

POST /customers/{external_customer_id}/checkout_url
This endpoint regenerates the Payment Provider Checkout URL of a Customer.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/customers/:external_id/checkout_url" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
    client.customers.checkout_url('external_id')
  except LagoApiError as e:
    repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.customers.checkout_url('external_id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  customer, err := lagoClient.Customer().CheckoutUrl("__EXTERNAL_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // customer is *lago.Customer
  fmt.Println(customer)
  }
  ```
</RequestExample>


# Update a customer

POST /customers
This endpoint creates a new customer.

<Warning>
  This endpoint performs an upsert operation.
</Warning>

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/customers" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "customer": {
        "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
        "address_line1": "5230 Penfield Ave",
        "address_line2": "",
        "city": "Woodland Hills",
        "country": "US",
        "currency": "USD",
        "email": "dinesh@piedpiper.test",
        "legal_name": "Coleman-Blair",
        "legal_number": "49-008-2965",
        "tax_identification_number": "EU123456789",
        "logo_url": "http://hooli.com/logo.png",
        "name": "Gavin Belson",
        "phone": "1-171-883-3711 x245",
        "state": "CA",
        "timezone": "Europe/Paris",
        "url": "http://hooli.com",
        "zipcode": "91364",
        "billing_configuration": {
          "invoice_grace_period": 3,
          "payment_provider": "stripe",
          "provider_customer_id": "cus_12345",
          "sync": true,
          "sync_with_provider": true,
          "document_locale": "fr",
          "provider_payment_methods": ["card", "sepa_debit", "us_bank_account", "bacs_debit", "link"]
        },
        "metadata": [
          {
            "key": "Purchase Order",
            "value": "123456789",
            "display_in_invoice": true
          }
        ],
        "tax_codes": ["french_standard_vat"]
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import Customer, CustomerBillingConfiguration

  client = Client(api_key='__YOUR_API_KEY__')

  metadata_object = Metadata(
    display_in_invoice=True,
    key='Purchase Order',
    value='123456789'
  )

  customer = Customer(
    external_id="5eb02857-a71e-4ea2-bcf9-57d8885990ba",
    address_line1="5230 Penfield Ave",
    address_line2=None,
    city="Woodland Hills",
    currency="USD",
    country="US",
    email="test@example.com",
    legal_name="Coleman-Blair",
    legal_number="49-008-2965",
    tax_identification_number="EU123456789",
    logo_url="http://hooli.com/logo.png",
    name="Test Name",
    phone="1-171-883-3711 x245",
    state="CA",
    timezone="Europe/Paris",
    url="http://hooli.com",
    zipcode="91364",
    billing_configuration=CustomerBillingConfiguration(
      invoice_grace_period=3,
      payment_provider="stripe",
      provider_customer_id="cus_12345",
      sync=true,
      sync_with_provider=true,
      document_locale="fr"
    ),
    metadata=MetadataList(__root__=[metadata_object])
  )

  try:
      client.customers.create(customer)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.customers.create(
    external_id: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    address_line1: "5230 Penfield Ave",
    address_line2: nil,
    city: "Woodland Hills",
    country: "US",
    currency: "USD",
    email: "dinesh@piedpiper.test",
    legal_name: "Coleman-Blair",
    legal_number: "49-008-2965",
    tax_identification_number: "EU123456789",
    logo_url: "http://hooli.com/logo.png",
    name: "Gavin Belson",
    phone: "1-171-883-3711 x245",
    state: "CA",
    timezone: "Europe/Paris",
    url: "http://hooli.com",
    zipcode: "91364",
    billing_configuration: {
      invoice_grace_period: 3,
      payment_provider: "stripe",
      provider_customer_id: "cus_12345",
      sync: true,
      sync_with_provider: true,
      document_locale: "fr",
      provider_payment_methods: ["card", "sepa_debit", "us_bank_account", "bacs_debit", "link"]
    },
    metadata: [
      {
        key: 'Purchas Order',
        value: '123456789',
        display_in_invoice: true
      }
    ],
    tax_codes: ["french_standard_vat"]
  )
  ```

  ```js Node.js
  import { BillingConfigurationCustomer } from "lago-javascript-client";

  const customerObject = {
    externalId: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    addressLine1: "5230 Penfield Ave",
    city: "Woodland Hills",
    currency: "EUR",
    country: "US",
    email: "dinesh@piedpiper.test",
    legalName: "Coleman-Blair",
    legalNumber: "49-008-2965",
    taxIdentificationNumber: "EU123456789",
    logoUrl: "http://hooli.com/logo.png",
    name: "Gavin Belson",
    phone: "1-171-883-3711 x245",
    state: "CA",
    timezone: "Europe/Paris",
    url: "http://hooli.com",
    zipcode: "91364",
    billingConfiguration: {
      invoiceGracePeriod: 3,
      paymentProvider:
        "stripe" as BillingConfigurationCustomer["paymentProvider"],
      providerCustomerId: "cus_12345",
      sync: true,
      syncWithProvider: true,
      documentLocale: "fr"
    },
    metadata: [
      {
        key: "Purchase Order",
        value: "123456789",
        displayInInvoice: true,
      },
    ],
  };

  await client.customers.createCustomer({ customer: customerObject });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  customerInput := &lago.CustomerInput{
      ExternalID:              "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      Name:                    "Gavin Belson",
      Email:                   "dinesh@piedpiper.test",
      AddressLine1:            "5230 Penfield Ave",
      AddressLine2:            "",
      City:                    "Woodland Hills",
      Country:                 "US",
      Currency:                "USD",
      State:                   "CA",
      Zipcode:                 "75001",
      LegalName:               "Coleman-Blair",
      LegalNumber:             "49-008-2965",
      TaxIdentificationNumber: "EU123456789",
      Phone:                   "+330100000000",
      Timezone:                "Europe/Paris",
      URL:                     "http://hooli.com",
      BillingConfiguration: &CustomerBillingConfigurationInput{
      InvoiceGracePeriod: 3,
      PaymentProvider: lago.PaymentProviderStripe,
      ProviderCustomerID: "cus_123456789",
      SyncWithProvider: true,
      DocumentLocale: "fr"
      },
      Metadata: [
      &CustomerMetadataInput{
          Key: "Purchase Order",
          Value: "123456789",
          DisplayInInvoice: true
      }
      ]
  }

  customer, err := lagoClient.Customer().Create(customerInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // You can use the same input to update the customer
  customer, err := lagoClient.Customer().Update(customerInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // customer is *lago.Customer
  fmt.Println(customer)
  }
  ```
</RequestExample>


# Batch usage events

POST /events/batch
This endpoint can be used to send a batch of usage records. Each request may include up to 100 events.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/events/batch" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  	"events": [
        {
          "transaction_id": "__UNIQUE_ID__",
          "external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
          "code": "__BILLABLE_METRIC_CODE__",
          "timestamp": $(date +%s),
          "properties": {
            "custom_field": 12
          }
        }
      ]
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import BatchEvent

  client = Client(api_key='__YOUR_API_KEY__')

  # Create a list of events
  batch_event = BatchEvent(events=[
      Event(
          transaction_id="__UNIQUE_ID_1__",
          external_subscription_id="__SUBSCRIPTION_ID_1__",
          code="__BILLABLE_METRIC_CODE__",
          timestamp=1650893379,
          properties={"custom_field": "custom"}
      ),
      Event(
          transaction_id="__UNIQUE_ID_2__",
          external_subscription_id="__SUBSCRIPTION_ID_2__",
          code="__BILLABLE_METRIC_CODE__",
          timestamp=1650893380,
          properties={"custom_field": "custom"}
      )
      # Add more events as needed
  ])
  try:
      client.events.batch_create(batch_event)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  # Create an array of event hashes
  events = [
    {
      transaction_id: "__UNIQUE_ID_1__",
      external_subscription_id: "__SUBSCRIPTION_ID_1__",
      code: "__BILLABLE_METRIC_CODE__",
      timestamp: Time.now.to_i,
      properties: {
        custom_field: "custom value 1"
      }
    },
    {
      transaction_id: "__UNIQUE_ID_2__",
      external_subscription_id: "__SUBSCRIPTION_ID_2__",
      code: "__BILLABLE_METRIC_CODE__",
      timestamp: Time.now.to_i,
      properties: {
        custom_field: "custom value 2"
      }
    }
    # Add more events as needed
  ]

  client.events.batch_create(events)
  ```

  ```js Javascript
  const batchEvent = [
    {
      transaction_id: "__UNIQUE_TRANSACTION_ID_1__",
      external_subscription_id: "__SUBSCRIPTION_ID_1__",
      code: "__BILLABLE_METRIC_CODE__",
      timestamp: 1650893379,
      properties: { customField: "custom1" },
    },
    {
      transaction_id: "__UNIQUE_TRANSACTION_ID_2__",
      external_subscription_id: "__SUBSCRIPTION_ID_2__",
      code: "__BILLABLE_METRIC_CODE__",
      timestamp: 1650893380,
      properties: { customField: "custom2" },
    },
    // Add more events as needed
  ];

  await client.events.createBatchEvents({ events: batchEvent });

  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    ctx := context.Background()
    lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

    event := lago.EventInput{
      TransactionID:          "__UNIQUE_TRANSACTION_ID__",
      ExternalSubscriptionID: "__UNIQUE_SUBSCRIPTION_ID__",
      Code:                   "__BILLABLE_METRIC_CODE__",
      Timestamp:              strconv.FormatInt(time.Now().Unix(), 10),
      Properties: map[string]interface{}{
        "nbusers": "12",
      },
    }

    batchInput := make([]lago.EventInput, 1)
    batchInput[0] = event

    res, err := lagoClient.Event().Batch(ctx, &batchInput)
  }
  ```
</RequestExample>


# Estimate an upcoming fee

POST /events/estimate_fees
Estimate the fees that would be created after reception of an event for a billable metric attached to one or multiple pay in advance charges.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/events/estimate_fees" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
        "event": {
            "external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
            "code": "__BILLABLE_METRIC_CODE__",
            "properties": {
              "custom_field": 12,
            }
        }
    }'
  ```

  ```python Python
  from lago_python_client.models import Event

  event = Event(
    external_subscription_id="__YOUR_SUBSCRIPTION_ID__",
    code="__BILLABLE_METRIC_CODE__",
  )

  client.events.estimate_fees(event)
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.events.estimate_fees(
    external_subscription_id: "__YOUR_SUBSCRIPTION_ID__",
    code: "__BILLABLE_METRIC_CODE__",
    properties: {
      custom_field: 12,
    }
  )
  ```

  ```js Javascript
  import { Client, getLagoError } from 'lago-javascript-client';

  const lagoClient = Client('__YOUR_API_KEY__');

  try {
      const { data } = await lagoClient.events.eventEstimateFees(estimateEvent);
  } catch (error) {
      const lagoError = await getLagoError<typeof lagoClient.events.eventEstimateFees>(error);
  }
  ```

  ```go Go
    import "fmt"
    import "github.com/getlago/lago-go-client"

    func main() {
      lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

      eventEstimateInput := &lago.EventEstimateFeesInput{
        ExternalSubscriptionID: "__YOUR_SUBSCRIPTION_ID__",
        Code:          "__BILLABLE_METRIC_CODE__",
        Properties: map[string]string{
          "custom_field": "12",
        },
      }

      err := lagoClient.Event().EstimateFees(eventEstimateInput)
      if err != nil {
        // Error is *lago.Error
        panic(err)
      }
    }
  ```
</RequestExample>


# The event object

Events represents usage measurement sent to lago application that will then be aggregated into invoice line items.



# Retrieve an event

GET /events/{transaction_id}
This endpoint is used for retrieving a specific usage measurement event that has been sent to a customer or a subscription.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/events/:transaction_id" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.events.find("transaction_id")
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.events.get('transaction_id')
  ```

  ```js Javascript
  await client.events.findEvent("__UNIQUE_TRANSACTION_ID__");
  ```
</RequestExample>


# List all events

GET /events
This endpoint is used for retrieving all events.



# Send usage event

POST /events
This endpoint is used for transmitting usage measurement events to either a designated customer or a specific subscription.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/events" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
        "event": {
            "transaction_id": "__UNIQUE_ID__",
            "external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
            "code": "__BILLABLE_METRIC_CODE__",
            "timestamp": $(date +%s),
            "properties": {
              "custom_field": 12
            }
        }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import Event

  client = Client(api_key='__YOUR_API_KEY__')

  event = Event(
    transaction_id="__UNIQUE_ID__",
    external_subscription_id="__UNIQUE_ID__",
    code="__BILLABLE_METRIC_CODE__",
    timestamp=1650893379,
    properties={"custom_field": "custom"}
  )

  try:
      client.events.create(event)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.events.create(
    transaction_id: "__UNIQUE_ID__",
    external_subscription_id: "__SUBSCRIPTION_ID__",
    code: "__BILLABLE_METRIC_CODE__",
    timestamp: Time.now.to_i,
    properties: {
        custom_field: 12
    }
  )
  ```

  ```js Javascript
  await client.events.createEvent({
    event: {
      transaction_id: "__UNIQUE_TRANSACTION_ID__",
      external_subscription_id: "__UNIQUE_SUBSCRIPTION_ID__",
      code: "__BILLABLE_METRIC_CODE__",
      timestamp: 1650893379,
      properties: { customField: "custom" },
    },
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  	ctx := context.Background()
  	lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

  	eventInput := &lago.EventInput{
  		TransactionID:          "__UNIQUE_TRANSACTION_ID__",
  		ExternalSubscriptionID: "__UNIQUE_SUBSCRIPTION_ID__",
  		Code:                   "__BILLABLE_METRIC_CODE__",
  		Timestamp:              strconv.FormatInt(time.Now().Unix(), 10),
  		Properties: map[string]interface{}{
  			"nbusers": "12",
  		},
  	}

  	res, err := lagoClient.Event().Create(ctx, eventInput)
  	if err != nil {
  		// err is *lago.Error
  		panic(err)
  	}
  	// res is *lago.Event
  	fmt.Println(*res)
  }
  ```
</RequestExample>


# Delete a fee

DELETE /fees/{lago_id}
This endpoint is used for deleting a specific fee that has not yet been invoiced



# The fee object

This object represents a line item of an invoice, handling amount, billed units and item description.



# List all fees

GET /fees
This endpoint is used for retrieving all fees that has been issued.

<RequestExample>
  ```bash cURL
  curl --location --request GET "$LAGO_URL/api/v1/fees?page=2&per_page=20&external_customer_id=hooli_1234" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client.fees.find_all({'per_page': 2, 'page': 1})
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client.fees.get_all({ per_page: 2, page: 3 })
  ```

  ```js Javascript
  await client.fees.findAllFees({ per_page: 2, page: 3 });
  ```

  ```go Go
  feeListInput := &lago.FeeListInput{
  PerPage: 1,
  Page: 1,
  CreatedAtFrom: "2022-01-01T00:00:00Z",
  CreatedAtTo: "2022-01-01T00:00:00Z",
  }

  feeResult, err := lagoClient.Fee().GetList(feeListInput)
  if err != nil {
  // Error is *lago.Error
  panic(err)
  }

  // feeResult is *lago.FeeResult
  fmt.Println(feeResult)
  ```
</RequestExample>


# Retrieve a fee

GET /fees/{lago_id}
This endpoint is used for retrieving a specific fee that has been issued.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  FEE_ID="__YOUR_FEE_ID__"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/fees/$FEE_ID" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.fees.find('id')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.fees.get('id')
  ```

  ```js Javascript
  await client.fees.findFee('fee-id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

  fee, err := lagoClient.Fees().Get("id")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // credit note is *lago.Fee
  fmt.Println(fee)
  }
  ```
</RequestExample>


# Update a fee

PUT /fees/{lago_id}
This endpoint is used for updating a specific fee that has been issued.

<RequestExample>
  ```bash cURL
  curl --location --request PUT "$LAGO_URL/api/v1/fees/1a901a90-1a90-1a90-1a90-1a901a901a90" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "fee": {
        "payment_status": "succeeded"
      }
    }'
  ```

  ```python Python
  from lago_python_client.models import Fee

  fee_update = Fee(
    payment_status="succeeded",
  )

  client.fees.update(fee_update, "1a901a90-1a90-1a90-1a90-1a901a901a90")
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client.fees.update({
    lago_id: "1a901a90-1a90-1a90-1a90-1a901a901a90",
    payment_status: "succeeded",
  })
  ```

  ```js Javascript
  const feeObject = {
    payment_status: "succeeded" as FeeObject["payment_status"],
  };

  await client.fees.updateFee("1a901a90-1a90-1a90-1a90-1a901a901a90", {
    fee: feeObject,
  });
  ```

  ```go Go
  feeId, _ := uuid.Parse("1a901a90-1a90-1a90-1a90-1a901a901a90")
  feeInput := &lago.FeeInput{
  LagoID: invoiceId,
  PaymentStatus: lago.FeePaymentStatusSucceeded,
  }

  fee, err := lagoClient.Fee().Update(feeInput)
  if err != nil {
  panic(err)
  }

  // fee is *lago.Fee
  fmt.Println(fee)
  }
  ```
</RequestExample>


# Getting started

Lago API allows your application to push customer information and metrics (events) from your application to the billing application.

To integrate it into your application, you can use the JSON HTTP API or one of
the Lago libraries (depending on your programing language or framework).

You must retrieve your API key from your account.

## Configuration[](#configuration "Direct link to heading")

<Tabs>
  <Tab title="Curl">
    ```shell
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request POST "$LAGO_URL/api/v1/..." \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '...'
    ```
  </Tab>

  <Tab title="Python">
    **Install package with pip**

    ```bash
    pip install lago-python-client
    ```

    **Usage**

    ```python
    from lago_python_client import Client

    # By default, this connects to Lago's hosted servers in the US region.
    client = Client(api_key='__YOUR_API_KEY__')

    # If you are self-hosting Lago or using a different server region,
    # specify the API URL to connect to the correct instance.
    # Replace '__YOUR_LAGO_URL__' with the appropriate URL for your Lago server.
    # Example: 'https://api.eu.getlago.com/api/v1' for the EU region.
    # client = Client(api_key='__YOUR_API_KEY__', api_url='__YOUR_LAGO_URL__')
    ```
  </Tab>

  <Tab title="Ruby">
    **Add the gem in your Gemfile**

    ```bash
    bundle add lago-ruby-client
    ```

    Or if bundler is not being used to manage dependencies, install the gem by
    executing:

    ```bash
    $ gem install lago-ruby-client
    ```

    **Usage**

    ```ruby
    require 'lago-ruby-client'

    # By default, this will connect to the US region of Lago's hosted servers.
    client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

    # If you are self-hosting Lago or using Lago in a different region (e.g., Europe),
    # you need to specify the API URL to connect to the correct server.
    # For example, you can provide the base URL for your specific Lago instance.
    # This example shows how to specify a different Lago server when needed.
    #
    # Replace '__YOUR_LAGO_URL__' with the appropriate URL of your Lago instance.
    # Example: 'https://api.eu.getlago.com/api/v1' for the EU region.
    #
    # client = Lago::Api::Client.new(
    #   api_key: '__YOUR_API_KEY__',
    #   api_url: '__YOUR_LAGO_URL__'
    # )
    ```
  </Tab>

  <Tab title="Javascript">
    **Install package with npm**

    ```bash
    npm install lago-javascript-client
    ```

    **Usage**

    ```js
    import { Client } from 'lago-javascript-client'
    // By default, this will connect to Lago's hosted servers in the US region.
    const client = Client('__YOUR_API_KEY__')

    // If you are self-hosting Lago or using a different region (e.g., EU),
    // you need to specify the base URL to connect to the correct Lago instance.
    // Replace '__YOUR_LAGO_URL__' with the appropriate URL for your Lago instance.
    // Example: 'https://api.eu.getlago.com/api/v1' for the EU region.
    // const client = Client('__YOUR_API_KEY__', { baseUrl: '__YOUR_LAGO_URL__' })
    ```
  </Tab>

  <Tab title="Go">
    **Install package**

    ```bash
      go get github.com/getlago/lago-go-client@v1
    ```

    **Usage**

    ```go
      import "github.com/getlago/lago-go-client"

      func main() {
        // By default, this will connect to Lago's hosted servers in the US region.
        lagoClient := lago.New().SetApiKey("__YOU_API_KEY__")

        // If you are self-hosting Lago or using a different region (e.g., EU),
        // you need to specify the base URL to connect to the correct Lago instance.
        // Replace '__YOUR_LAGO_URL__' with the appropriate URL for your Lago instance.
        // Example: 'https://api.eu.getlago.com/api/v1' for the EU region.
        // lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__").SetBaseURL("__YOUR_LAGO_URL__")
      }
    ```
  </Tab>
</Tabs>


# Create a one-off invoice

POST /invoices
This endpoint is used for issuing a one-off invoice.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/invoices" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "invoice": {
        "external_customer_id": "hooli_1234",
        "currency": "USD",
        "fees": [
          {
            "add_on_code": "setup_fee",
            "units": 2.5,
            "unit_amount_cents": 1200,
            "description": "This is a description.",
            "tax_codes": ["french_standard_vat]
          }
        ]
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import InvoiceFee, OneOffInvoice, InvoiceFeesList

  client = Client(api_key='__YOUR_API_KEY__')

  fee_object = InvoiceFee(
    add_on_code='setup_fee',
    units=2.5,
    unit_amount_cents=1200,
    description='This is a description.'
  )

  invoice_create = OneOffInvoice(
    external_customer_id="hooli_1234",
    currency="USD",
    fees=InvoiceFeesList(__root__=[fee_object])
  )

  try:
      client.invoices.create(invoice_create)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.invoices.create({
    external_customer_id: "hooli_1234",
    currency: 'USD',
    fees: [
      {
        add_on_code: 'setup_fee',
        units: 2.5,
        unit_amount_cents: 1200,
        description: 'This is a description.'
      }
    ]
  })
  ```

  ```js Javascript
  const invoiceObject = {
    external_customer_id: "hooli_1234",
    currency: "USD",
    fees: [
      {
        add_on_code: "setup_fee",
        description: "This is a description.",
        units: 2.5,
        unit_amount_cents: 1200,
      },
    ],
  };

  await client.invoices.createInvoice({
    invoice: invoiceObject,
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  invoiceInput := &lago.OneOffInput{
      ExternalCustomerId: custID,
          currency: "USD",
      Fees: [
      &InvoiceFeesInput{
          AddOnCode: "setup_fee",
          Description: "This is a description.",
          Units: 2.5,
          UnitAmountCents: 1200
      }
      ]
  }

  invoice, err := lagoClient.Invoice().Create(invoiceInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // invoice is *lago.Invoice
  fmt.Println(invoice)
  }
  ```
</RequestExample>


# Download an invoice

POST /invoices/{lago_id}/download
This endpoint is used for downloading a specific invoice PDF document.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  INVOICE_ID="__YOUR_INVOICE_ID__"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/invoices/$INVOICE_ID/download" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  invoice = None
  try:
      invoice = client.invoices.download('__YOUR_INVOICE_ID__')  # Invoice ID
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.invoices.download('__YOUR_INVOICE_ID__') // Invoice ID
  ```

  ```js Javascript
  await client.invoices.downloadInvoice('invoice-id');
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  invoice, err := lagoClient.Invoice().Download("__YOUR_INVOICE_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // invoice is *lago.Invoice
  fmt.Println(invoice)

  // If the invoice has to be generated, the response is empty
  // And you will get a webhook `invoice.generated`
  }
  ```
</RequestExample>


# Finalize an invoice

PUT /invoices/{lago_id}/finalize
This endpoint is used for finalizing a draft invoice.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request PUT "$LAGO_URL/api/v1/invoices/:lago_invoice_id/finalize" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{}'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.invoices.finalize('__INVOICE_ID__')  # Invoice ID
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.invoices.finalize('__INVOICE_ID__') // Invoice ID
  ```

  ```js Javascript
  await client.invoices.finalizeInvoice("invoice-id");
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  invoice, err := lagoClient.Invoice().Finalize("__YOUR_INVOICE_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // invoice is *lago.Invoice
  fmt.Println(invoice)
  }
  ```
</RequestExample>


# List all invoices

GET /invoices
This endpoint is used for retrieving all invoices.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/invoices?page=2&per_page=20&external_customer_id=hooli_1234" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.invoices.find_all({'per_page': 2, 'page': 1})
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.invoices.get_all({ per_page: 2, page: 3 })
  ```

  ```js Javascript
  await client.invoices.findAllInvoices({ per_page: 2, page: 3 });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  invoiceListInput := &lago.InvoiceListInput{
      PerPage: 1,
      Page: 1,
      IssuingDateFrom: "2022-01-01",
      IssuingDateTo: "2022-01-01",
  }

  invoiceResult, err := lagoClient.Invoice().GetList(invoiceListInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // invoiceResult is *lago.InvoiceResult
  fmt.Println(invoiceResult)
  }
  ```
</RequestExample>


# Retrieve an invoice

GET /invoices/{lago_id}
This endpoint is used for retrieving a specific invoice that has been issued.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/invoices/:lago_id" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.invoices.find('lago_id')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.invoices.get('lago_id')
  ```

  ```js Javascript
  await client.invoices.findInvoice('lago-id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  invoice, err := lagoClient.Invoice().Get("lago_id")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // invoice is *lago.Invoice
  fmt.Println(invoice)
  }
  ```
</RequestExample>


# The invoice object

This object represents an invoice generated by Lago for a specific customer. This invoice summarizes the fees generated by a subscription, usage-based charges, prepaid credit purchases, or one-off invoices.



# Generate a payment URL

POST /invoices/{lago_id}/payment_url
This endpoint generates a checkout link for a specific invoice.



# Refresh an invoice

PUT /invoices/{lago_id}/refresh
This endpoint is used for refreshing a draft invoice.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request PUT "$LAGO_URL/api/v1/invoices/:lago_invoice_id/refresh" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{}'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.invoices.refresh('__INVOICE_ID__')  # Invoice ID
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.invoices.refresh('__INVOICE_ID__') // Invoice ID
  ```

  ```js Javascript
  await client.invoices.refreshInvoice('invoice-id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  invoice, err := lagoClient.Invoice().Refresh("__INVOICE_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // invoice is *lago.Invoice
  fmt.Println(invoice)
  }
  ```
</RequestExample>


# Retry an invoice payment

POST /invoices/{lago_id}/retry_payment
This endpoint resends an invoice for collection and retry a payment.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  INVOICE_ID="__INVOICE_ID__"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/invoices/$INVOICE_ID/retry_payment" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  invoice = None
  try:
      invoice = client.invoices.retry_payment('__INVOICE_ID__')  # Invoice ID
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.invoices.retry_payment('__INVOICE_ID__') // Invoice ID
  ```

  ```js Javascript
  await client.invoices.retryPayment("invoice-id");
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  invoice, err := lagoClient.Invoice().RetryPayment("__INVOICE_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // invoice is *lago.Invoice
  fmt.Println(invoice)

  // If the invoice has to be generated, the response is empty
  // And you will get a webhook `invoice.generated`
  }
  ```
</RequestExample>


# Retry an invoice finalization

POST /invoices/{lago_id}/retry
This endpoint is used for retrying to generate a failed invoice.



# Update an invoice

PUT /invoices/{lago_id}
This endpoint is used for updating an existing invoice.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request PUT "$LAGO_URL/api/v1/invoices/:lago_id" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "invoice": {
        "payment_status": "succeeded",
        "metadata": [
          {
            "id": "__METADATA_ID__",
            "key": "digital_ref_id",
            "value": "INV-0123456-98765"
          }
        ]
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import InvoicePaymentStatusChange

  client = Client(api_key='__YOUR_API_KEY__')

  metadata_object = InvoiceMetadata(
    key='key',
    value='value'
  )

  invoice_update = Invoice(
    payment_status="succeeded",
    metadata=InvoiceMetadataList(__root__=[metadata_object])
  )

  try:
      client.invoices.update(invoice_update, "__INVOICE_ID__")
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception

  # Deprecated

  payment_status_change = InvoicePaymentStatusChange(
    payment_status="succeeded"
  )

  try:
      client.invoices.update(payment_status_change, "__INVOICE_ID__")
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.invoices.update({
    lago_id: "__INVOICE_ID__",
    payment_status: "succeeded",
    metadata: [
      {
        key: 'key',
        value: 'value'
      }
    ]
  })
  ```

  ```js Javascript
  const invoiceObject = {
    payment_status: "succeeded" as InvoiceObject["payment_status"],
    metadata: [
      {
        key: "key",
        value: "value",
      },
    ],
  };

  await client.invoices.updateInvoice("invoice-id", {
    invoice: invoiceObject,
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  invoiceId, _ := uuid.Parse("__YOUR_INVOICE_ID__")
  invoiceInput := &lago.InvoiceInput{
      LagoID: invoiceId,
          PaymentStatus: lago.InvoicePaymentStatusSucceeded,
      Metadata: [
      &InvoiceMetadataInput{
          Key: "Key",
          Value: "Value"
      }
      ]
  }

  invoice, err := lagoClient.Invoice().Update(invoiceInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // invoice is *lago.Invoice
  fmt.Println(invoice)
  }
  ```
</RequestExample>


# Void an invoice

POST /invoices/{lago_id}/void
This endpoint is used for voiding an invoice. You can void an invoice only when it's in a `finalized` status, and the payment status is not `succeeded`.



# The organization object

This object represents your organization. You can define all invoicing details and settings within it.



# Update your organization

PUT /organizations
This endpoint is used to update your own organization's settings.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request PUT "$LAGO_URL/api/v1/organizations" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "organization": {
        "webhook_url": "https://webhook.brex.com",
        "country": "US",
        "address_line1": "100 Brex Street",
        "address_line2": null,
        "state": "NYC",
        "zipcode": "10000",
        "email": "brex@brex.com",
        "city": "New York",
        "legal_name": null,
        "legal_number": null,
        "net_payment_term": 30,
        "tax_identification_number": "US123456789",
        "timezone": "America/New_York",
        "default_currency": "USD",
        "document_numbering": "per_customer",
        "document_number_prefix": "LAGO-INV",
        "email_settings": [
          "invoice.finalized",
          "credit_note.created"
        ],
        "billing_configuration": {
          "invoice_footer": "This is my customer footer",
          "invoice_grace_period": 3,
          "document_locale": "en",
          "vat_rate": 12.5
        }
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import Organization, OrganizationBillingConfiguration

  client = Client(api_key='__YOUR_API_KEY__')

  params = Organization(
    timezone="America/New_York",
    webhook_url="https://webhook.brex.com",
    email_settings=["invoice.finalized"],
    tax_identification_number="US123456789",
    default_currency="USD",
    document_numbering= "per_customer",
    document_number_prefix= "LAGO-INV",
    billing_configuration=OrganizationBillingConfiguration(
      invoice_footer="This is my customer footer",
      invoice_grace_period=3,
      document_locale="en",
      vat_rate=12.5
    )
  )

  try:
      client.organizations.update(params)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  update_params = {
    timezone: 'America/New_York',
    webhook_url: 'https://webhook.brex.com',
    email_settings: ['invoice.finalized'],
    tax_identification_number: "US123456789",
    default_currency: "USD",
    document_numbering: 'per_customer',
    document_number_prefix: 'LAGO-INV',
    billing_configuration: {
      invoice_footer="This is my customer footer",
      invoice_grace_period=3,
      document_locale: "en",
      vat_rate: 12.5
    }
  }
  client.organizations.update(update_params)
  ```

  ```js Javascript
  await client.organizations.updateOrganization({
    organization: {
      timezone: "America/New_York",
      webhook_url: "https://webhook.brex.com",
      email_settings: ["invoice.finalized"],
      tax_identification_number: "US123456789",
      default_currency: "USD",
      document_numbering: "per_customer",
      document_number_prefix: "LAGO-INV",
      billing_configuration: {
        invoice_footer: "This is my customer footer",
        invoice_grace_period: 3,
        document_locale: "en",
        vat_rate: 12.5,
      },
    },
  });
  ```

  ```go Go
    import "fmt"
    import "github.com/getlago/lago-go-client"

    func main() {
      lagoClient := lago.New().
        SetApiKey("__YOUR_API_KEY__")

      organizationInput := &lago.OrganizationInput{
        LegalName:              "Legal Name",
        Timezone:               "America/New_York",
        EmailSettings:          ["invoice.finalized"],
        TaxIdentificationNumber: "US123456789",
        DefaultCurrency: "USD",
        BillingConfiguration: &OrganizationBillingConfigurationInput{
          InvoiceFooter: "This is my customer foote",
          InvoiceGracePeriod: 3,
          DocumentLocale: "en",
          VatRate: 12.5,
        }
      }

      organization, err := lagoClient.Organization().Update(organizationInput)
      if err != nil {
        // Error is *lago.Error
        panic(err)
      }

      // organization is *lago.Organization
      fmt.Println(organization)
    }
  ```
</RequestExample>


# Create a payment request

POST /payment_requests
This endpoint is used to create a payment request to collect payments of overdue invoices of a given customer



# List all payment requests

GET /payment_requests
This endpoint is used to list all existing payment requests.



# The payment request object

This object represents payment request of a group of overdue invoices for which a payment intent can be created, to settle the overdue balance.



# Create a plan

POST /plans
This endpoint creates a plan with subscription and usage-based charges. It supports flexible billing cadence (in-advance or in-arrears) and allows for both recurring and metered charges.



# Delete a plan

DELETE /plans/{code}
This endpoint deletes a specific plan. Note that this plan could be associated with active subscriptions.



# List all plans

GET /plans
This endpoint retrieves all existing plans.



# Retrieve a plan

GET /plans/{code}
This endpoint retrieves a specific plan.



# The plan object

This object represents a plan. This plan can then be assigned to a customer.



# Update a plan

PUT /plans/{code}
This endpoint updates a specific plan with subscription and usage-based charges. It supports flexible billing cadence (in-advance or in-arrears) and allows for both recurring and metered charges.



# Currencies

List of accepted currencies (ISO 4217).

| Code  | Currency name                             |
| ----- | ----------------------------------------- |
| `AED` | `United Arab Emirates Dirham`             |
| `AFN` | `Afghan Afghani`                          |
| `ALL` | `Albanian Lek`                            |
| `AMD` | `Armenian Dram`                           |
| `ANG` | `Netherlands Antillean Gulden`            |
| `AOA` | `Angolan Kwanza`                          |
| `ARS` | `Argentine Peso`                          |
| `AUD` | `Australian Dollar`                       |
| `AWG` | `Aruban Florin`                           |
| `AZN` | `Azerbaijani Manat`                       |
| `BAM` | `Bosnia and Herzegovina Convertible Mark` |
| `BBD` | `Barbadian Dollar`                        |
| `BDT` | `Bangladeshi Taka`                        |
| `BGN` | `Bulgarian Lev`                           |
| `BIF` | `Burundian Franc`                         |
| `BMD` | `Bermudian Dollar`                        |
| `BND` | `Brunei Dollar`                           |
| `BOB` | `Bolivian Boliviano`                      |
| `BRL` | `Brazilian Real`                          |
| `BSD` | `Bahamian Dollar`                         |
| `BWP` | `Botswana Pula`                           |
| `BYN` | `Belarusian Ruble`                        |
| `BZD` | `Belize Dollar`                           |
| `CAD` | `Canadian Dollar`                         |
| `CDF` | `Congolese Franc`                         |
| `CHF` | `Swiss Franc`                             |
| `CLF` | `Unidad de Fomento`                       |
| `CLP` | `Chilean Peso`                            |
| `CNY` | `Chinese Renminbi Yuan`                   |
| `COP` | `Colombian Peso`                          |
| `CRC` | `Costa Rican Colón`                       |
| `CVE` | `Cape Verdean Escudo`                     |
| `CZK` | `Czech Koruna`                            |
| `DJF` | `Djiboutian Franc`                        |
| `DKK` | `Danish Krone`                            |
| `DOP` | `Dominican Peso`                          |
| `DZD` | `Algerian Dinar`                          |
| `EGP` | `Egyptian Pound`                          |
| `ETB` | `Ethiopian Birr`                          |
| `EUR` | `Euro`                                    |
| `FJD` | `Fijian Dollar`                           |
| `FKP` | `Falkland Pound`                          |
| `GBP` | `British Pound`                           |
| `GEL` | `Georgian Lari`                           |
| `GIP` | `Gibraltar Pound`                         |
| `GMD` | `Gambian Dalasi`                          |
| `GNF` | `Guinean Franc`                           |
| `GTQ` | `Guatemalan Quetzal`                      |
| `GYD` | `Guyanese Dollar`                         |
| `HKD` | `Hong Kong Dollar`                        |
| `HNL` | `Honduran Lempira`                        |
| `HRK` | `Croatian Kuna`                           |
| `HTG` | `Haitian Gourde`                          |
| `HUF` | `Hungarian Forint`                        |
| `IDR` | `Indonesian Rupiah`                       |
| `ILS` | `Israeli New Sheqel`                      |
| `INR` | `Indian Rupee`                            |
| `ISK` | `Icelandic Króna`                         |
| `JMD` | `Jamaican Dollar`                         |
| `JPY` | `Japanese Yen`                            |
| `KES` | `Kenyan Shilling`                         |
| `KGS` | `Kyrgyzstani Som`                         |
| `KHR` | `Cambodian Riel`                          |
| `KMF` | `Comorian Franc`                          |
| `KRW` | `South Korean Won`                        |
| `KYD` | `Cayman Islands Dollar`                   |
| `KZT` | `Kazakhstani Tenge`                       |
| `LAK` | `Lao Kip`                                 |
| `LBP` | `Lebanese Pound`                          |
| `LKR` | `Sri Lankan Rupee`                        |
| `LRD` | `Liberian Dollar`                         |
| `LSL` | `Lesotho Loti`                            |
| `MAD` | `Moroccan Dirham`                         |
| `MDL` | `Moldovan Leu`                            |
| `MGA` | `Malagasy Ariary`                         |
| `MKD` | `Macedonian Denar`                        |
| `MMK` | `Myanmar Kyat`                            |
| `MNT` | `Mongolian Tögrög`                        |
| `MOP` | `Macanese Pataca`                         |
| `MRO` | `Mauritanian Ouguiya`                     |
| `MUR` | `Mauritian Rupee`                         |
| `MVR` | `Maldivian Rufiyaa`                       |
| `MWK` | `Malawian Kwacha`                         |
| `MXN` | `Mexican Peso`                            |
| `MYR` | `Malaysian Ringgit`                       |
| `MZN` | `Mozambican Metical`                      |
| `NAD` | `Namibian Dollar`                         |
| `NGN` | `Nigerian Naira`                          |
| `NIO` | `Nicaraguan Córdoba`                      |
| `NOK` | `Norwegian Krone`                         |
| `NPR` | `Nepalese Rupee`                          |
| `NZD` | `New Zealand Dollar`                      |
| `PAB` | `Panamanian Balboa`                       |
| `PEN` | `Peruvian Sol`                            |
| `PGK` | `Papua New Guinean Kina`                  |
| `PHP` | `Philippine Peso`                         |
| `PKR` | `Pakistani Rupee`                         |
| `PLN` | `Polish Złoty`                            |
| `PYG` | `Paraguayan Guaraní`                      |
| `QAR` | `Qatari Riyal`                            |
| `RON` | `Romanian Leu`                            |
| `RSD` | `Serbian Dinar`                           |
| `RUB` | `Russian Ruble`                           |
| `RWF` | `Rwandan Franc`                           |
| `SAR` | `Saudi Riyal`                             |
| `SBD` | `Solomon Islands Dollar`                  |
| `SCR` | `Seychellois Rupee`                       |
| `SEK` | `Swedish Krona`                           |
| `SGD` | `Singapore Dollar`                        |
| `SHP` | `Saint Helenian Pound`                    |
| `SLL` | `Sierra Leonean Leone`                    |
| `SOS` | `Somali Shilling`                         |
| `SRD` | `Surinamese Dollar`                       |
| `STD` | `São Tomé and Príncipe Dobra`             |
| `SZL` | `Swazi Lilangeni`                         |
| `THB` | `Thai Baht`                               |
| `TJS` | `Tajikistani Somoni`                      |
| `TOP` | `Tongan Paʻanga`                          |
| `TRY` | `Turkish Lira`                            |
| `TTD` | `Trinidad and Tobago Dollar`              |
| `TWD` | `New Taiwan Dollar`                       |
| `TZS` | `Tanzanian Shilling`                      |
| `UAH` | `Ukrainian Hryvnia`                       |
| `UGX` | `Ugandan Shilling`                        |
| `USD` | `United States Dollar`                    |
| `UYU` | `Uruguayan Peso`                          |
| `UZS` | `Uzbekistan Som`                          |
| `VND` | `Vietnamese Đồng`                         |
| `VUV` | `Vanuatu Vatu`                            |
| `WST` | `Samoan Tala`                             |
| `XAF` | `Central African Cfa Franc`               |
| `XCD` | `East Caribbean Dollar`                   |
| `XOF` | `West African Cfa Franc`                  |
| `XPF` | `Cfp Franc`                               |
| `YER` | `Yemeni Rial`                             |
| `ZAR` | `South African Rand`                      |
| `ZMW` | `Zambian Kwacha`                          |


# Document locales



## Document locales supported

List of accepted locales for documents (ISO 639-1).

| Document language  | Code |
| ------------------ | ---- |
| German             | `de` |
| English            | `en` |
| French             | `fr` |
| Italian            | `it` |
| Norwegian (Bokmål) | `nb` |
| Spanish            | `es` |
| Swedish            | `sv` |

## How to add a new language

You can contribute to Lago's open-source project by helping us translate documents. The new language will then be added to the list of supported locales and available to the entire Lago Community.

The document template includes translation keys for:

*   Invoices related to subscriptions, add-ons and prepaid credits;
*   Credit notes;
*   Data formatting (e.g. amounts and dates); and
*   Syntax (i.e. sentence structure).

<Info>
  The names of your billable metrics, plans, add-ons, coupons and wallets are defined in the app. There are no keys to translate them.
</Info>

To add a new language:

1.  [Download the document template](https://uploads-ssl.webflow.com/635119506e36baf5c267fecd/657743325ca22f3e97f23728_doc-locales-invoice-templates.pdf) to see where each key is located;
2.  Use the text file below to provide translations for the new language; and
3.  Send the new text file to [hello@getlago.com](mailto:hello@getlago.com), so that we can review it and add it to the codebase.

Thanks for your time and support!

```json
en:
  money:   
    //[AA] format: $4,500.00
    format: '%u%n'
    decimal_mark: '.'
    thousands_separator: ','
  date:
    formats: 
      //[AB] format: Dec. 01, 2022
      default: '%b. %d, %Y'
    abbr_day_names: 
      - Sun
      - Mon
      - Tue
      - Wed
      - Thu
      - Fri
      - Sat
    abbr_month_names: 
      - Jan
      - Feb
      - Mar
      - Apr
      - May
      - Jun
      - Jul
      - Aug
      - Sep
      - Oct
      - Nov
      - Dec
    day_names: 
      - Sunday
      - Monday
      - Tuesday
      - Wednesday
      - Thursday
      - Friday
      - Saturday
    month_names: 
      - January
      - February
      - March
      - April
      - May
      - June
      - July
      - August
      - September
      - October
      - November
      - December
    order:
      - :year
      - :month
      - :day


=====================================================================


en:
  invoice:
    [1.1] document_name: "Invoice"
    [1.2] document_tax_name: "Tax invoice"
    [1.3] invoice_number: "Invoice Number"
    [1.4] issue_date: "Issue Date"
    [1.5] payment_term: "Net payment term"
    [1.6] payment_term_days: "%{net_payment_term} days"
    [1.7] bill_from: "From"
    [1.8] bill_to: "Bill to"
    [1.9] tax_identification_number: "Tax ID: %{tax_identification_number}"
    [1.10] due_date: "Due %{date}"
    [1.11] item: "Item"
    [1.12] unit: "Unit"
    [1.13] unit_price: "Unit price"
    [1.14] tax_rate: "Tax rate"
    [1.15] amount: "Amount"
    [1.16] sub_total_without_tax: "Sub total (excl. tax)"
    [1.17] tax_name: "%{name} (%{rate}% on %{amount})"
    [1.18] sub_total_with_tax: "Sub total (incl. tax)"
    [1.19] credit_notes: "Credit Notes"
    [1.20] prepaid_credits: "Prepaid credits"
    [1.21] total_due: "Total due"
    [1.22] powered_by: "Powered by"

    [AC] details: "%{resource} details"
    [2.1] date_from: "Fees from"
    [2.2] date_to: "to"
    [AD] subscription_interval: "%{plan_interval} subscription - %{plan_name}"
    [2.3] weekly: "Weekly"
    [2.4] monthly: "Monthly"
    [2.5] quarterly: "Quarterly"
    [2.6] yearly: "Yearly"

    graduated & graduated percentage:
      [2.7] fee_per_unit_for_the_first: "Fee per unit for the first {to}"
      [2.8] fee_per_unit_for_the_next: "Fee per unit for the next §{from} to 8{to}"
      [2.9] fee_per_unit_for_the_last: "Fee per unit for {from} and above"
      [2.10] flat_fee_for_the_first: "Flat fee for first 8{to}"
      [2.11] flat_fee_for_the_next "Flat fee for the next {from} to (to}"
      [2.12] flat_fee_for_the_last: "Flat fee for {from} and above"
      [2.13] sub_total: "Subtotal"
    
    [2.14] fee_prorated: "The fee is prorated on days of usage, the displayed unit price is an average"

    package:
      [2.15] free_units_for_the_first: "Free units for the first {count}"
      [2.16] fee_per_package: "Fee per package"
      [2.17] fee_per_package_unit_price: "§{amount} per {package_size}"

    percentage:
      [2.18] total_event: "Total event"
      [2.19] free_units_per_transaction:
        one: "Free units for 1 transaction"
        other: "Free units for {count} transactions"
      [2.20] percentage_rate_on_amount: "Rate on the amount"
      [2.21] fee_per_transaction: "Fixed fee per transaction"
      [2.22] adjustment_per_transaction: "Adjustment for min/max per transaction"
  
    [2.23] true_up_metric: "%{metric} • True-up"
    [2.24] true_up_details: "Minimum spend of %{min_amount} prorated on days of usage"
    
    volume:
      [2.25] fee_per_unit: "Fee per unit"
      [2.26] flat_fee_for_all_units: "Flat fee for all units"
    
    [2.27] units_prorated_per_period: "Units prorated per second per %{period}"
    [2.28] week: "week"
    [2.29] month: "month"
    [2.30] quarter: "quarter"
    [2.31] year: "year"
    [2.32] total: "Total"

    [3.1] breakdown: "Breakdown"
    [3.2] breakdown_of: "Breakdown of %{fee_filter_display_name}"
    [3.3] breakdown_for_days: "Used %{breakdown_duration} out of %{breakdown_total_duration} days"
    [3.4] notice_prorated: "Regardless of when an event is received, the unit is not prorated, we charge the full price."
    [3.5] notice_full: "If a unit is added or removed during the monthly plan, we calculate the prorated price based on the ratio of days remaining or used to the total number of days in the plan. For instance, if 15 days are left in the plan, we multiply the price by 15/31, and if a unit was used for 10 days, we multiply the price by 10/31."

    [4.1] prepaid_credits_with_value: "Prepaid credits - %{wallet_name}"

    //For invoices with old versions
    total_credits_with_value: "Total credits amount: %{credit_amount} credits"
    all_subscriptions: "All subscriptions"
    all_usage_based_fees: "All consumption fees"
    tax: "Taxes"
    fees_from_to_date: "Consumption fees from %{from_date} to %{to_date}"
    tax_name_with_details: "%{name} (%{rate}%)"
    subscription: "Subscription"
    sub_total: "Subtotal"
    usage_based_fees: "Consumption fees"
    list_of_charges: "List of consumption fees from %{from} to %{to}"
    see_breakdown: "See breakdown below"
    total_unit_interval: "Total number of units: %{events_count} event(s) for %{units}"
    total_unit: "Total number of units: %{units}"
    amount_with_tax: "Amount (incl. tax)"
    amount_without_tax: "Amount (excl. tax)"
    

=====================================================================


en:
  credit_note:
    [5.1] document_name: "Credit note"
    [5.2] credit_note_number: "Credit note number"
    [5.3] invoice_number: "Invoice number"
    [5.4] issue_date: "Issue date"
    [5.5] credit_from: "From"
    [5.6] credit_to: "Credit to"
    [5.7] tax_identification_number: "ID fiscal: %{tax_identification_number}"
    [5.8] refunded_notice: "Refunded on %{issuing_date}"
    [5.9] credited_notice: "Credited on customer balance on %{issuing_date}"
    [5.10] credited_refunded_notice: "Credited on customer balance and refunded on %{issuing_date}"
    [5.11] item: "Item"
    [5.12] tax_rate: "Tax rate"
    [5.13] amount: "Amount (excl. tax)"
    [5.14] subscription: "Subscription"
    [5.15] true_up_metric: "%{metric} • True-up"
    [5.16] coupon_adjustment: "Coupons"
    [5.17] sub_total_without_tax: "Sub total (excl. tax)"
    [5.18] tax: "%{name} (%{rate}% on %{amount})"
    [5.19] credited_on_customer_balance: "Credited on customer balance"
    [5.20] refunded: "Refunded"
    [5.21] total: "Total"
    [5.22] powered_by: "Powered by"


=====================================================================


en:
  email:
    invoice:
      finalized:
        [6.1] subject: "Your invoice from {organization_name} #%{invoice_number}"
        [6.2] invoice_from: "Invoice from %{organization_name}"
        [6.3] due_date: "Due %{date}"
        [6.4] invoice_number: "Invoice number"
        [6.5] issue_date: "Issue date"
        [6.6] download: "Download invoice for details"
    credit_note:
      created:
        [6.7] subject: "Your credit note from %{organization_name} #%{credit_note_number}"
        [6.8] credit_note_from: "Credit note from %{organization_name}"
        [6.9] refunded_notice: "Refunded on %{date}"
        [6.10] credited_notice: "Credited on customer balance on %{date}"
        [6.11] credited_refunded_notice: "Credited on customer balance and refunded on %{date}"
        [6.12] credit_note_number: "Credit note number"
        [6.13] invoice_number: "Invoice number"
        [6.14] issue_date: "Issue date"
        [6.15] download: "Download invoice for details"
    [6.98] questions: "Questions? Contact us at"
    [6.99] powered_by_lago: "Powered by"


=====================================================================


en:
  customer_portal:
    [7.1] powered_by: "Powered by"
    [7.2] customer_information: "Customer information"
    [7.3] name: "Name"
    [7.4] name_not_provided: "Name not provided"
    [7.5] legal_name: "Legal name"
    [7.6] legal_name_not_provided: "Legal name not provided"
    [7.7] legal_number: "Legal number"
    [7.8] legal_number_not_provided: "Legal number not provided"
    [7.9] tax_id: "Tax ID number"
    [7.10] tax_id_not_provided: "Tax ID number not provided"
    [7.11] email: "Email"
    [7.12] email_not_provided: "Email not provided"
    [7.13] address: "Address"
    [7.14] address_not_provided: "Address not provided"
    [7.15] invoice_history: "Invoice history"
    [7.16] invoices_search: "Search invoices"
    [7.17] issuing_date: "Issuing date"
    [7.18] invoice_number: "Invoice number"
    [7.19] amount: "Amount"
    [7.20] payment: "Payment "
    [7.21] download: "Download PDF"
    [7.22] unpaid: "Unpaid"
    [7.23] paid: "Paid"
    [7.24] invoices_empty_state: "There are currently no invoices attached to this customer. Please check back later, or contact us if you notice any issues."
    [7.25] expired_customer_portal_header: "For security reasons, this page has expired"
    [7.26] error_customer_portal_header: "Something went wrong token is invalid or has expired"
    [7.27] something_went_wrong: "Something went wrong"
    [7.28] please_refresh: "Please refresh the page or contact us if the error persists."
    [7.29] refresh: "Refresh the page"
    [7.30] not_found: "This invoice cannot be found"
    [7.31] change_keyword: "Could you enter another keyword?"
```


# Timezones

List of accepted timezones (TZ database).

*   `UTC`
*   `Africa/Algiers`
*   `Africa/Cairo`
*   `Africa/Casablanca`
*   `Africa/Harare`
*   `Africa/Johannesburg`
*   `Africa/Monrovia`
*   `Africa/Nairobi`
*   `America/Argentina/Buenos_Aires`
*   `America/Bogota`
*   `America/Caracas`
*   `America/Chicago`
*   `America/Chihuahua`
*   `America/Denver`
*   `America/Godthab`
*   `America/Guatemala`
*   `America/Guyana`
*   `America/Halifax`
*   `America/Indiana/Indianapolis`
*   `America/Juneau`
*   `America/La_Paz`
*   `America/Lima`
*   `America/Los_Angeles`
*   `America/Mazatlan`
*   `America/Mexico_City`
*   `America/Monterrey`
*   `America/Montevideo`
*   `America/New_York`
*   `America/Phoenix`
*   `America/Puerto_Rico`
*   `America/Regina`
*   `America/Santiago`
*   `America/Sao_Paulo`
*   `America/St_Johns`
*   `America/Tijuana`
*   `Asia/Almaty`
*   `Asia/Baghdad`
*   `Asia/Baku`
*   `Asia/Bangkok`
*   `Asia/Chongqing`
*   `Asia/Colombo`
*   `Asia/Dhaka`
*   `Asia/Hong_Kong`
*   `Asia/Irkutsk`
*   `Asia/Jakarta`
*   `Asia/Jerusalem`
*   `Asia/Kabul`
*   `Asia/Kamchatka`
*   `Asia/Karachi`
*   `Asia/Kathmandu`
*   `Asia/Kolkata`
*   `Asia/Krasnoyarsk`
*   `Asia/Kuala_Lumpur`
*   `Asia/Kuwait`
*   `Asia/Magadan`
*   `Asia/Muscat`
*   `Asia/Novosibirsk`
*   `Asia/Rangoon`
*   `Asia/Riyadh`
*   `Asia/Seoul`
*   `Asia/Shanghai`
*   `Asia/Singapore`
*   `Asia/Srednekolymsk`
*   `Asia/Taipei`
*   `Asia/Tashkent`
*   `Asia/Tbilisi`
*   `Asia/Tehran`
*   `Asia/Tokyo`
*   `Asia/Ulaanbaatar`
*   `Asia/Urumqi`
*   `Asia/Vladivostok`
*   `Asia/Yakutsk`
*   `Asia/Yekaterinburg`
*   `Asia/Yerevan`
*   `Atlantic/Azores`
*   `Atlantic/Cape_Verde`
*   `Atlantic/South_Georgia`
*   `Australia/Adelaide`
*   `Australia/Brisbane`
*   `Australia/Darwin`
*   `Australia/Hobart`
*   `Australia/Melbourne`
*   `Australia/Perth`
*   `Australia/Sydney`
*   `Europe/Amsterdam`
*   `Europe/Athens`
*   `Europe/Belgrade`
*   `Europe/Berlin`
*   `Europe/Bratislava`
*   `Europe/Brussels`
*   `Europe/Bucharest`
*   `Europe/Budapest`
*   `Europe/Copenhagen`
*   `Europe/Dublin`
*   `Europe/Helsinki`
*   `Europe/Istanbul`
*   `Europe/Kaliningrad`
*   `Europe/Kiev`
*   `Europe/Lisbon`
*   `Europe/Ljubljana`
*   `Europe/London`
*   `Europe/Madrid`
*   `Europe/Minsk`
*   `Europe/Moscow`
*   `Europe/Paris`
*   `Europe/Prague`
*   `Europe/Riga`
*   `Europe/Rome`
*   `Europe/Samara`
*   `Europe/Sarajevo`
*   `Europe/Skopje`
*   `Europe/Sofia`
*   `Europe/Stockholm`
*   `Europe/Tallinn`
*   `Europe/Vienna`
*   `Europe/Vilnius`
*   `Europe/Volgograd`
*   `Europe/Warsaw`
*   `Europe/Zagreb`
*   `Europe/Zurich`
*   `GMT+12`
*   `Pacific/Apia`
*   `Pacific/Auckland`
*   `Pacific/Chatham`
*   `Pacific/Fakaofo`
*   `Pacific/Fiji`
*   `Pacific/Guadalcanal`
*   `Pacific/Guam`
*   `Pacific/Honolulu`
*   `Pacific/Majuro`
*   `Pacific/Midway`
*   `Pacific/Noumea`
*   `Pacific/Pago_Pago`
*   `Pacific/Port_Moresby`
*   `Pacific/Tongatapu`


# Create a subscription

POST /subscriptions
This endpoint assigns a plan to a customer, creating or modifying a subscription. Ideal for initial subscriptions or plan changes (upgrades/downgrades).

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/subscriptions" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
    "subscription": {
      "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
      "plan_code": "premium",
      "name": "Repository A",
      "external_id": "my_sub_1234567890",
      "billing_time": "anniversary",
      "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"
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
    }
  }'
  ```

  ```python Python
  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__')

  subscription = Subscription(
    external_customer_id="5eb02857-a71e-4ea2-bcf9-57d8885990ba",
    plan_code="startup_plan",
    external_id="sub_id_123456789",
    name="Repository A",
    subscription_at="2022-08-08T00:00:00Z",
    ending_at= "2023-08-08T00:00:00Z",
    billing_time="anniversary"
  )

  try:
      client.subscriptions.create(subscription)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.subscriptions.create(
    external_customer_id: "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    plan_code: "startup_plan",
    external_id: "sub_id_123456789",
    name: "Repository A",
    subscription_at: "2022-08-08T00:00:00Z",
    ending_at: "2023-08-08T00:00:00Z",
    billing_time: "anniversary"
  )
  ```

  ```js Javascript
  import { Client, SubscriptionObject } from "lago-javascript-client";

  const subscriptionObject = {
    external_customer_id: "5eb02857-a71e-4ea2-bcf9-57d8885990ba",
    plan_code: "statup_plan",
    external_id: "sub_id_123456789",
    name: "Repository A",
    subscription_at: "2022-08-08T00:00:00Z",
    ending_at: "2023-08-08T00:00:00Z",
    billing_time: "anniversary" as SubscriptionObject["billingTime"],
  };

  await client.subscriptions.createSubscription({
    subscription: subscriptionObject,
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  subscriptionInput := &lago.SubscriptionInput{
      ExternalCustomerID: "5eb02857-a71e-4ea2-bcf9-57d8885990ba",
      PlanCode:           "startup_plan",
      SubscriptionAt:     "2022-08-08T00:00:00Z",
      EndingAt:           "2023-08-08T00:00:00Z",
      BillingTime:        lago.Anniversary,
  }

  subscription, err := lagoClient.Subscription().Create(subscriptionInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // subscription is *lago.Subscription
  fmt.Println(subscription)
  }
  ```
</RequestExample>


# List all subscriptions

GET /subscriptions
This endpoint retrieves all active subscriptions.

<RequestExample>
  ```bash cURL
  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"
  ```

  ```python Python
  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
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

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

  ```js Javascript
  await client.subscriptions.findAllSubscriptions({
    external_customer_id: "123",
    page: 1,
  });
  ```
</RequestExample>


# Retrieve subscription lifetime usage

GET /subscriptions/{external_id}/lifetime_usage
This endpoint allows you to retrieve the total lifetime usage of a subscription.



# Retrieve a subscription

GET /subscriptions/{external_id}
This endpoint retrieves a specific subscription.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/subscriptions/:external_id" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  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('externalId')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.subscriptions.get('external_id')
  ```

  ```js Javascript
  await client.subscriptions.findSubscription("external_id");
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  subscriptionResult, err := lagoClient.Subscription().Get("__YOUR_SUBSCRIPTION_EXTERNAL_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // subscription is *lago.Subscription
  fmt.Println(subscription)
  }
  ```
</RequestExample>


# The lifetime usage object

This object represents the total lifetime usage of a subscription, particularly useful for progressive billing.



# The subscription object

This object represents the assignation of plan to one of the customer of your business.



# Terminate a subscription

DELETE /subscriptions/{external_id}
This endpoint allows you to terminate a subscription.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"
  EXTERNAL_ID="__YOUR_SUBSCRIPTION_ID__"

  curl --location --request DELETE "$LAGO_URL/api/v1/subscriptions/$EXTERNAL_ID?status=pending" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.subscriptions.destroy('external_id')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')
  client.subscriptions.destroy("5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba")
  ```

  ```js Javascript
  await client.subscriptions.destroySubscription("external_id");
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  subscription, err := lagoClient.Subscription().Terminate("__EXTERNAL_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // subscription is *lago.Subscription
  fmt.Println(subscription)
  }
  ```
</RequestExample>


# Update a subscription

PUT /subscriptions/{external_id}
This endpoint allows you to update a subscription.

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

  ```python Python
  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
  ```

  ```ruby Ruby
  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')
  ```

  ```js Javascript
  await client.subscriptions.updateSubscription("external_id", {
    subscription: {
      name: "new name",
      subscription_at: "2022-08-08T00:00:00Z",
      ending_at: "2023-08-08T00:00:00Z",
    },
  });
  ```
</RequestExample>


# Update subscription lifetime usage

PUT /subscriptions/{external_id}/lifetime_usage
This endpoint allows you to update the total lifetime usage of a subscription for migration purposes.



# Create a tax rate

POST /taxes
This endpoint creates a new tax representing a customizable tax rate applicable to either the organization or a specific customer.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/taxes" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "tax": {
        "name": "TVA",
        "code": "french_standard_vat",
        "rate": "20.0",
        "description": "French standard VAT",
        "applied_to_organization": false
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import Tax

  client = Client(api_key='__YOUR_API_KEY__')

  tax = Tax(
  		name="TVA",
      code="french_standard_vat",
      rate="20.0",
      description="French standard VAT",
      applied_to_organization=false
  )
  try:
      client.taxes.create(tax)
  except LagoApiError as e:
  		# do something on error or raise your own exception
      repair_broken_state(e)
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  tax = {
  	name: "TVA",
    code: "french_standard_vat",
    rate: "20.0",
    description: "French standard VAT",
    applied_to_organization: false
  }

  client.taxes.create(tax)
  ```

  ```js Javascript
  const taxObject = {
    name: "TVA",
    code: "french_standard_vat",
    rate: "20.0",
    description: "French standard VAT",
    applied_to_organization: false,
  };

  await client.taxes.createTax({ tax: taxObject });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

    taxInput := &lago.TaxInput{
      Name:                  "TVA",
      Code:                  "french_standard_vat",
      Rate:                  "20.0",
      Description:           "French standard VAT",
      AppliedToOrganization: false,
    }

    tax, err := lagoClient.Tax().Create(taxInput)
    if err != nil {
      // Error is *lago.Error
      panic(err)
    }

    // tax is *lago.Tax
    fmt.Println(tax)
  }
  ```
</RequestExample>


# Delete a tax rate

DELETE /taxes/{code}
This endpoint is used to delete a tax.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request DELETE "$LAGO_URL/api/v1/taxes/:code" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.taxes.destroy('code')
  except LagoApiError as e:
      repair_broken_state(e)
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.taxes.destroy('code')
  ```

  ```js Javascript
  await client.taxes.destroyTax('code')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

    tax, err := lagoClient.Tax().Delete("__YOUR_TAX_CODE__")
    if err != nil {
      panic(err)
    }

    fmt.Println(tax)
  }
  ```
</RequestExample>


# List all tax rates

GET /taxes
This endpoint retrieves all existing taxes representing a customizable tax rate applicable to either the organization or a specific customer.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/taxes?per_page=2&page=1" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.taxes.find_all({'per_page': 2, 'page': 1})
  except LagoApiError as e:
      repair_broken_state(e)
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.taxes.get_all({ per_page: 2, page: 3 })
  ```

  ```js Javascript
  await client.taxes.findAllTaxes({ per_page: 2, page: 3 });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

    taxListInput := &lago.TaxListInput{
      PerPage: 1,
      Page: 1,
    }

    taxResult, err := lagoClient.Tax().GetList(taxListInput)
    if err != nil {
      panic(err)
    }

    fmt.Println(taxResult)
  }
  ```
</RequestExample>


# Retrieve a tax rate

GET /taxes/{code}
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.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/taxes/:code" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.taxes.find('code')
  except LagoApiError as e:
      repair_broken_state(e)
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.taxes.get('code')
  ```

  ```js Javascript
  await client.taxes.findTax("code");
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

    tax, err := lagoClient.Tax().Get("__YOUR_TAX_CODE__")
    if err != nil {
      panic(err)
    }

    fmt.Println(tax)
  }
  ```
</RequestExample>


# The tax object

This object represents a customizable tax rate applicable to either the organization or a specific customer.



# Update a tax rate

PUT /taxes/{code}
This endpoint updates an existing tax representing a customizable tax rate applicable to either the organization or a specific customer.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request PUT "$LAGO_URL/api/v1/taxes" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "tax": {
        "name": "french vat",
        "code": "french_vat_2",
        "rate": 20.00,
        "description": "Standard VAT",
        "applied_to_organization": false
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import Tax

  client = Client(api_key='__YOUR_API_KEY__')

  tax = Tax(
  		name="TVA",
      code="french_standard_vat",
      rate="20.0",
      description="French standard VAT",
      applied_to_organization=false
  )
  try:
      client.taxes.update(tax, "french_standard_vat")
  except LagoApiError as e:
  		# do something on error or raise your own exception
      repair_broken_state(e)
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  tax = {
  	name: "TVA",
    code: "french_standard_vat",
    rate: "20.0",
    description: "French standard VAT",
    applied_to_organization: false
  }

  client.taxes.update(tax, "french_standard_vat")
  ```

  ```js Javascript
  const taxObject = {
    name: "TVA",
    code: "french_standard_vat",
    rate: "20.0",
    description: "French standard VAT",
    applied_to_organization: false,
  };

  await client.taxes.updateTax("french_standard_vat", { tax: taxObject });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
    lagoClient := lago.New().SetApiKey("__YOUR_API_KEY__")

    taxInput := &lago.TaxInput{
      Name:                  "TVA",
      Code:                  "french_standard_vat",
      Rate:                  "20.0",
      Description:           "French standard VAT",
      AppliedToOrganization: false,
    }

    tax, err := lagoClient.Tax().Update(taxInput)
    if err != nil {
      // Error is *lago.Error
      panic(err)
    }

    // tax is *lago.Tax
    fmt.Println(tax)
  }
  ```
</RequestExample>


# Create a wallet

POST /wallets
This endpoint is used to create a wallet with prepaid credits.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/wallets" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "wallet": {
        "name": "Prepaid",
        "rate_amount": "1.5",
        "paid_credits": "20.0",
        "granted_credits": "10.0",
        "currency": "USD",
        "expiration_at": "2022-07-07",
        "external_customer_id": "hooli_1234"
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import Wallet

  client = Client(api_key='__YOUR_API_KEY__')

  wallet = Wallet(
    name='Prepaid',
    rate_amount='1.5',
    paid_credits='20.0',
    granted_credits='10.0',
    currency='USD',
    expiration_at='2022-07-07T23:59:59Z',
    external_customer_id='hooli_1234'
  )

  try:
      client.wallets.create(wallet)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.wallets.create({
      name: 'Prepaid',
      rate_amount: '1.5',
      paid_credits: '20.0',
      granted_credits: '10.0',
      currency: 'USD',
      expiration_at: '2022-07-07T23:59:59Z',
      external_customer_id: 'hooli_1234'
  })
  ```

  ```js Javascript
  await client.wallets.createWallet({
    wallet: {
      name: "Prepaid",
      currency: "USD",
      rate_amount: 1.5,
      paid_credits: 20.0,
      granted_credits: 10.0,
      expiration_at: "2022-07-07T23:59:59Z",
      external_customer_id: "hooli_1234",
    },
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  walletInput := &lago.WalletInput{
      Name:               "Prepaid",
      RateAmount:         "1.5",
      PaidCredits:        "20.0"
      GrantedCredits:     "10.0",
      Currency:           "USD",
      ExpirationAt:       "2022-07-07T23:59:59Z",
      ExternalCustomerID: "hooli_1234",
  }

  wallet, err := lagoClient.Wallet().Create(walletInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // wallet is *lago.Wallet
  fmt.Println(wallet)
  }
  ```
</RequestExample>


# List all wallets

GET /wallets
This endpoint is used to list all wallets with prepaid credits.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/wallets?external_customer_id&per_page=2&page=1" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.wallets.find_all({'external_customer_id': hooli_1234, 'per_page': 2, 'page': 1})
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.wallets.get_all({ external_customer_id: hooli_1234, per_page: 2, page: 3 })
  ```

  ```js Javascript
  await client.wallets.findAllWallets({
    external_customer_id: "hooli_1234",
    per_page: 2,
    page: 3,
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  walletListInput := &lago.WalletListInput{
      PerPage: 10,
      Page: 1,
      ExternalCustomerID: hooli_1234
  }

  walletResult, err := lagoClient.Wallet().GetList(walletListInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // wallet is *lago.WalletResult
  fmt.Println(walletResult)
  }
  ```
</RequestExample>


# List all wallet transactions

GET /wallets/{lago_id}/wallet_transactions
This endpoint is used to list all wallet transactions.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/wallets/:id/wallet_transactions?per_page=2&page=1" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.wallet_transactions.find_all({'per_page': 2, 'page': 1})
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.wallet_transactions.get_all({ per_page: 2, page: 3 })
  ```

  ```js Javascript
  await client.wallets.findAllWalletTransactions("wallet-id", {
    per_page: 2,
    page: 3,
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  walletTransactionListInput := &lago.WalletTransactionListInput{
      PerPage: 1,
      Page: 1,
      WalletId: 12345,
  }

  walletTransactionResult, err := lagoClient.WalletTransaction().GetList(walletTransactionListInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // walletTransactionResult is *lago.WalletTransactionResult
  fmt.Println(walletTransactionResult)
  }
  ```
</RequestExample>


# Retrieve a wallet

GET /wallets/{lago_id}
This endpoint is used to retrieve an existing wallet with prepaid credits.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/wallets/:id" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.wallets.find('id')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.wallets.get('id')
  ```

  ```js Javascript
  await client.wallets.findWallet('wallet-id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  wallet, err := lagoClient.Wallet().Get("__ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // wallet is *lago.Wallet
  fmt.Println(wallet)
  }
  ```
</RequestExample>


# Terminate a wallet

DELETE /wallets/{lago_id}
This endpoint is used to terminate an existing wallet with prepaid credits.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request DELETE "$LAGO_URL/api/v1/wallets/:wallet_id" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.wallets.destroy('id')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.wallets.destroy('id')
  ```

  ```js Javascript
  await client.wallets.destroyWallet('wallet-id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  wallet, err := lagoClient.Wallet().Delete("__ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // wallet is *lago.Wallet
  fmt.Println(wallet)
  }
  ```
</RequestExample>


# Top-up a wallet

POST /wallet_transactions
This endpoint is used to top-up an active wallet.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/wallet_transactions" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "wallet_transaction": {
        "wallet_id": "wallet_1234",
        "paid_credits": "20.0",
        "granted_credits": "10.0"
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import WalletTransaction

  client = Client(api_key='__YOUR_API_KEY__')

  transaction = WalletTransaction(
    wallet_id='wallet_1234',
    paid_credits='20.0',
    granted_credits='10.0'
  )

  try:
      client.wallet_transactions.create(transaction)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.wallet_transactions.create({
      wallet_id: 'wallet_1234',
      paid_credits: '20.0',
      granted_credits: '10.0'
  })
  ```

  ```js Javascript
  await client.walletTransactions.createWalletTransaction({
    wallet_transaction: {
      wallet_id: "wallet_1234",
      paid_credits: 20.0,
      granted_credits: 10.0,
    },
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  walletTransactionInput := &lago.WalletTransactionInput{
      WalletId:           "wallet_1234",
      PaidCredits:        "20.0"
      GrantedCredits:     "10.0",
  }

  transactions, err := lagoClient.WalletTransaction().Create(walletTransactionInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // wallet is *lago.Wallet
  fmt.Println(transactions)
  }
  ```
</RequestExample>


# Update a wallet

PUT /wallets/{lago_id}
This endpoint is used to update an existing wallet with prepaid credits.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request PUT "$LAGO_URL/api/v1/wallets/:lago_id" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "wallet": {
        "name": "Prepaid Credits",
        "expiration_at": "2022-07-07T23:59:59Z"
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import Wallet

  client = Client(api_key='__YOUR_API_KEY__')

  wallet = Wallet(
    name='Prepaid Credits',
    expiration_at='2022-07-07T23:59:59Z'
  )

  try:
      client.wallets.update(wallet, '__WALLET_ID__')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.wallets.update({
      name: 'Prepaid Credits',
      expiration_at: '2022-07-07T23:59:59Z',
  }, '__WALLET_ID__')
  ```

  ```js Javascript
  await client.wallets.updateWallet("wallet-id", {
    wallet: { name: "Prepaid Credits", expiration_at: "2022-07-07T23:59:59Z" },
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  walletInput := &lago.WalletInput{
      Name:            "Prepaid Credits",
      ExpirationAt:    "2022-07-07T23:59:59Z"
  }

  wallet, err := lagoClient.Wallet().Update(walletInput, "__WALLET_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // wallet is *lago.Wallet
  fmt.Println(wallet)
  }
  ```
</RequestExample>


# The wallet object

This object represents a wallet, holding free or prepaid credits. 



# The wallet transaction object

This object represents a wallet transaction. It is used for topping up or voiding prepaid credits.



# Create a webhook endpoint

POST /webhook_endpoints
This endpoint is used to create a webhook endpoint.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request POST "$LAGO_URL/api/v1/webhook_endpoints" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "webhook_endpoint": {
        "webhook_url": "https://foo.bar",
        "signature_algo": "hmac"
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import WebhookEndpoint

  client = Client(api_key='__YOUR_API_KEY__')

  webhook_endpoint = WebhookEndpoint(
    webhook_url='https://foo.bar',
    signature_algo: 'hmac'
  )

  try:
      client.webhook_endpoints.create(webhook_endpoint)
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.webhook_endpoints.create({
      webhook_url: 'https://foo.bar',
      signature_algo: 'hmac'
  })
  ```

  ```js Javascript
  await client.webhookEndpoints.createWebhookEndpoint({
    webhook_endpoint: {
      webhook_url: "https://foo.bar",
      signature_algo: "hmac",
    },
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  webhookEndpointInput := &lago.WebhookEndpointInput{
      WebhookURL: "https://foo.bar"
  }

  webhookEndpoint, err := lagoClient.WebhookEndpoint().Create(webhookEndpointInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // webhookEndpoint is *lago.WebhookEndpoint
  fmt.Println(webhookEndpoint)
  }
  ```
</RequestExample>


# Delete a webhook endpoint

DELETE /webhook_endpoints/{id}

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request DELETE "$LAGO_URL/api/v1/webhook_endpoints/:id" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.webhook_endpoints.destroy('id')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.webhook_endpoints.destroy('id')
  ```

  ```js Javascript
  await client.webhookEndpoints.deleteWebhookEndpoint('id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  webhookEndpoint, err := lagoClient.WebhookEndpoint().Delete("id")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // webhookEndpoint is *lago.WebhookEndpoint
  fmt.Println(webhookEndpoint)
  }
  ```
</RequestExample>


# Retrieve a webhook endpoint

GET /webhook_endpoints
This endpoint is used to list all webhook endpoints.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/webhook_endpoints?per_page=2&page=1" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.webhook_endpoints.find_all({'per_page': 2, 'page': 1})
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.webhook_endpoints.get_all({ per_page: 2, page: 3 })
  ```

  ```js Javascript
  await client.webhookEndpoints.findAllWebhookEndpoints({
    per_page: 2,
    page: 3,
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  webhookEndpointListInput := &lago.WebhookEndpointListInput{
      PerPage: 10,
      Page: 1
  }

  webhookEndpointResult, err := lagoClient.WebhookEndpoint().GetList(WebhookEndpointListInput)
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // webhookEndpointResult is *lago.WebhookEndpointResult
  fmt.Println(webhookEndpointResult)
  }
  ```
</RequestExample>


# List all webhook endpoints

GET /webhook_endpoints/{lago_id}
This endpoint is used to retrieve an existing webhook endpoint.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request GET "$LAGO_URL/api/v1/webhook_endpoints/:id" \
    --header "Authorization: Bearer $API_KEY"
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError

  client = Client(api_key='__YOUR_API_KEY__')

  try:
      client.webhook_endpoints.find('id')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.webhook_endpoints.get('id')
  ```

  ```js Javascript
  await client.webhookEndpoints.findWebhookEndpoint('webhook-endpoint-id')
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  webhookEndpoint, err := lagoClient.WebhookEndpoint().Get("__ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // webhookEndpoint is *lago.WebhookEndpoint
  fmt.Println(webhookEndpoint)
  }
  ```
</RequestExample>


# Update a webhook endpoint

PUT /webhook_endpoints/{lago_id}
This endpoint is used to update an existing webhook endpoint.

<RequestExample>
  ```bash cURL
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"

  curl --location --request PUT "$LAGO_URL/api/v1/webhook_endpoints/:lago_id" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "webhook_endpoint": {
        "webhook_url": "https://foo.bar",
        "signature_algo": "hmac"
      }
    }'
  ```

  ```python Python
  from lago_python_client.client import Client
  from lago_python_client.exceptions import LagoApiError
  from lago_python_client.models import WebhookEndpoint

  client = Client(api_key='__YOUR_API_KEY__')

  webhook_endpoint = WebhookEndpoint(
    webhook_url='https://foo.bar',
    signature_algo: 'hmac'
  )

  try:
      client.webhook_endpoints.update(webhook_endpoint, '__WEBHOOK_ENDPOINT_ID__')
  except LagoApiError as e:
      repair_broken_state(e)  # do something on error or raise your own exception
  ```

  ```ruby Ruby
  require 'lago-ruby-client'

  client = Lago::Api::Client.new(api_key: '__YOUR_API_KEY__')

  client.webhook_endpoints.update({
      webhook_url: 'https://foo.bar',
      signature_algo: 'hmac'
  }, '__WEBHOOK_ENDPOINT_ID__')
  ```

  ```js Javascript
  await client.webhook_endpoints.updateWebhookEndpoint("webhook-endpoint-id", {
    webhook_endpoint: { webhook_url: "https://foo.bar" },
  });
  ```

  ```go Go
  import "fmt"
  import "github.com/getlago/lago-go-client"

  func main() {
  lagoClient := lago.New().
      SetApiKey("__YOUR_API_KEY__")

  webhookEndpointInput := &lago.WebhookEndpointInput{
      WebhookURL: "https://foo.bar"
  }

  webhookEndpoint, err := lagoClient.WebhookEndpoint().Update(webhookEndpointInput, "__WEBHOOK_ENDPOINT_ID__")
  if err != nil {
      // Error is *lago.Error
      panic(err)
  }

  // webhookEndpoint is *lago.WebhookEndpoint
  fmt.Println(webhookEndpoint)
  }
  ```
</RequestExample>


# The webhook endpoint object

This object represents the webhook endpoint used for listening to Lago’s events



# Format & Signature

Webhooks are HTTP notifications sent from Lago to your application.

The messages are sent as a `POST` to the URL defined in the settings of your
Lago workspace.

## Message format[](#message-format "Direct link to heading")

`POST __WEBHOOK_URL__`

```json
{
  "webhook_type": "__TYPE__",
  "object_type": "OBJECT_TYPE",
  "__OBJECT__": {}
}
```

## Signature[](#signature "Direct link to heading")

Allong with the payload the message contains both `X-Lago-Signature` and `X-Lago-Signature-Algorithm` HTTP header.

It is used to ensure the message is Coming from Lago and that the message has not been altered.

To verify the signature, you must decode the signature and compare the result with the body of the webhook.

You can choose between 2 differents signatures algorithm during your webhook endpoints creation, `hmac` or `jwt`.
Please note that `jwt` is our original signature and is used by default.

### JWT Signature

#### 1. Retrieve the public key[](#1-retrieve-the-public-key "Direct link to heading")

<CodeGroup>
  ```py Python
  from lago_python_client import Client

  client = Client(api_key='__YOUR_API_KEY__')
  webhooks_public_key = client.webhooks().public_key()
  ```

  ```js Node.js
  import Client from "lago-nodejs-client";

  let client = new Client("__YOUR_API_KEY__");
  let webhooksPublicKey = client.webhookPublicKey();
  ```

  ```ruby Ruby
  require 'net/http'

  api_key = "__YOUR_API_KEY__"
  uri = URI('https://api.getlago.com/api/v1/webhooks/public_key')

  http = Net::HTTP.new(uri.host, uri.port)
  http.use_ssl = true

  response = http.send_request(
    'GET',
    uri.request_uri,
    '',
    { 'Authorization' => "Bearer #{api_key}" }
  )

  webhooks_public_key = response.body
  ```
</CodeGroup>

<br />

<Tip>
  You should persist the public key on your side to avoid querying it for each
  webhook.
</Tip>

#### 2. Decode and validate the signature[](#2-decode-and-validate-the-signature "Direct link to heading")

<CodeGroup>
  ```py Python
  import jwt

  decoded_signature = jwt.decode(
    request.headers.get('X-Lago-Signature'),
    webhooks_public_key,
    algorithms=['RS256'],
    issuer="https://api.getlago.com"
  )

  decoded_signature['data'] == request.body
  ```

  ```js Node.js
  import jwt from "jsonwebtoken";

  let token = request.header("X-Lago-Signature");

  jwt.verify(
    token,
    webhooksPublicKey,
    {
      algorithms: ["RS256"],
      issuer: "https://api.getlago.com",
    },
    function (err, payload) {
      payload === request.body;
    }
  );
  ```

  ```ruby Ruby
  require 'openssl'
  require 'jwt'

  decoded_signature = JWT.decode(
    request.headers['X-Lago-Signature'],
    OpenSSL::PKey::RSA.new(Base64.decode64(webhooks_public_key)),
    true,
    {
      algorithm: 'RS256',
      iss: "https://api.getlago.com",
      verify_iss: true,
    },
  ).first

  decoded_signature['data'] == request.body
  ```
</CodeGroup>

### HMAC Signature

#### Decode and validate the signature

<CodeGroup>
  ```py Python
  import hmac
  import base64

  calc_sig = hmac.new(LAGO_API_KEY, request.body.encode(), 'sha256').digest()
  base64_sig = base64.b64encode(calc_sig).decode()
  request.headers.get('X-Lago-Signature') == base64_sig
  ```

  ```js Node.js
  import crypto from 'crypto';

  const signature = request.header('X-Lago-Signature')
  const hmac = crypto.createHmac('sha256', 'YOUR_ORGANIZATION_API_KEY')

  hmac.update(request.body)

  const encodedBody = hmac.digest().toString('base64')

  signature == encodedBody
  ```

  ```ruby Ruby
  require 'openssl'

  signature =  request.headers['X-Lago-Signature']
  hmac = OpenSSL::HMAC.digest('sha-256', 'YOUR_ORGANIZATION_API_KEY', request.body)
  base64_hmac = Base64.strict_encode64(hmac)

  base64_hmac == signature
  ```

  ```php PHP
  $signature = $_SERVER['X-Lago-Signature'];

  $requestBody = file_get_contents('php://input');
  $hmac = hash_hmac('sha256', $requestBody, 'YOUR_ORGANIZATION_API_KEY', true);
  $base64Signature = base64_encode($hmac);

  $valid = hash_equals($signature, $base64Signature);
  ```
</CodeGroup>


# Messages

Below is a list of the event types we currently send. Please note that additional event types may be introduced in the future, so your code should be flexible enough to accommodate new types as they arise. Our objective is to maintain a consistent and predictable event structure, making it easier to integrate and handle messages, along with the objects they affect.

## Credit notes and refunds

<ParamField path="credit_note.created" type="data.object">
  [Credit note object](/api-reference/credit-notes/credit-note-object). Sent when a new credit note has been issued for a customer. This will allow your application to proceed with the refund.
</ParamField>

<ParamField path="credit_note.generated" type="data.object">
  [Credit note object](/api-reference/credit-notes/credit-note-object). Sent when the PDF file has been generated for a credit note. This will allow your application to retrieve the PDF credit note.
</ParamField>

<ParamField path="credit_note.refund_failure" type="data.object">
  `credit_note_payment_provider_refund_error` object. Sent when there is an error related to the refund process (i.e. the payment provider cannot refund the customer).
</ParamField>

## Customers

### External payment providers

<ParamField path="customer.payment_provider_created" type="data.object">
  [Customer object](/api-reference/customers/object). Sent when a customer is successfully created in the payment provider’s application. This allows you to retrieve the identifier assigned to the customer by the payment service provider.
</ParamField>

<ParamField path="customer.checkout_url_generated" type="data.object">
  `payment_provider_customer_checkout_url` object. Sent when a checkout link is issued for a customer.
</ParamField>

<ParamField path="customer.payment_provider_error" type="data.object">
  `payment_provider_customer_error` object. Sent when there is an error related to the creation of a customer in the payment provider’s system.
</ParamField>

<ParamField path="invoice.payment_failure" type="data.object">
  `payment_provider_invoice_payment_error` object. Sent when there is an error related to the payment process. Usually occurs when no valid payment method is defined for the customer in the payment service provider’s application.
</ParamField>

<ParamField path="invoice.payment_dispute_lost" type="data.object">
  `payment_dispute_lost` object. Sent whenever a dispute or a chargeback is lost within your payment provider.
</ParamField>

### External accounting providers

<ParamField path="customer.accounting_provider_created" type="data.object">
  [Customer object](/api-reference/customers/object). Sent when a customer is successfully created in the accounting provider’s application (like NetSuite). This allows you to retrieve the identifier assigned to the customer by the accounting service provider.
</ParamField>

<ParamField path="customer.accounting_provider_error" type="data.object">
  `accounting_provider_customer_error` object. Sent when there is an error related to the accounting provider sync. Usually occurs when something went wrong in the accounting service provider’s application.
</ParamField>

### External tax providers

<ParamField path="customer.tax_provider_error" type="data.object">
  `tax_provider_error` object. Sent when there is an error related to the tax provider sync. This usually occurs due to issues with item mappings, customer definitions, or within the service provider’s application.
</ParamField>

## Event ingestion

<ParamField path="events.errors" type="data.object">
  Sent by the health check process when some events received in the previous hour do not match the validation rules.
</ParamField>

<ParamField path="events.error" type="data.object" deprecated="true">
  This webhook is deprecated and no longer sent in Lago `v0.50.0-beta` and above. It was sent when there was an error related to the creation of an event.
</ParamField>

## Invoices

<ParamField path="invoice.drafted" type="data.object">
  [Invoice object](/api-reference/invoices/invoice-object). Sent when a new invoice is in draft.
</ParamField>

<ParamField path="invoice.created" type="data.object">
  [Invoice object](/api-reference/invoices/invoice-object). Sent when an invoice is finalized.
  This event serves as a signal to your application that the invoice processing is complete and you can proceed with the necessary billing actions or procedures.
</ParamField>

<ParamField path="invoice.one_off_created" type="data.object">
  [Invoice object](/api-reference/invoices/invoice-object). Sent when a one-off invoice is created. Only add-ons can be applied to one-off invoices.
</ParamField>

<ParamField path="invoice.paid_credit_added" type="data.object">
  [Invoice object](/api-reference/invoices/invoice-object). Sent when prepaid credits have been paid and added to the customer's wallet. You can use this information to generate a PDF invoice or collect the payment.
</ParamField>

<ParamField path="invoice.generated" type="data.object">
  [Invoice object](/api-reference/invoices/invoice-object). Sent when the PDF file has been generated for a customer invoice. This will allow your application to retrieve the PDF invoice.
</ParamField>

<ParamField path="invoice.payment_status_updated" type="data.object">
  [Invoice object](/api-reference/invoices/invoice-object). Sent when the payment status of an invoice is updated based on information provided by the payment provider.
</ParamField>

<ParamField path="invoice.payment_overdue" type="data.object">
  [Invoice object](/api-reference/invoices/invoice-object). Sent when the payment of an invoice is considered as overdue.
</ParamField>

<ParamField path="invoice.voided" type="data.object">
  [Invoice object](/api-reference/invoices/invoice-object). Sent when an invoice is voided.
</ParamField>

## Payments

<ParamField path="payment.requires_action" type="data.object">
  This message is triggered when a payment requires additional validation or confirmation, typically via 3D Secure (3DS). This is commonly seen in regions like India or when enhanced customer authentication is necessary.
  The `url` field contains the checkout link that initiates 3D Secure (3DS) validation for your customers. The `return_url` is the page displayed once the 3DS process is completed.
</ParamField>

<ParamField path="payment_request.created" type="data.object">
  [Payment request object](/api-reference/payment-requests/payment-request-object). Sent when a manual payment request has been triggered, to request payment for the overdue balance.
</ParamField>

<ParamField path="payment_request.payment_failure" type="data.object">
  [Payment request object](/api-reference/payment-requests/payment-request-object). Sent when the payment attached to a payment request has failed. The `provider_error` field indicates the error code and message from the payment provider.
</ParamField>

<ParamField path="payment_request.payment_status_updated" type="data.object">
  [Payment request object](/api-reference/payment-requests/payment-request-object). Sent when the payment attached to a payment request is updated to a new payment status, through the \`payment\_status field.
</ParamField>

## Subscriptions and fees

<ParamField path="fee.created" type="data.object">
  [Fee object](/api-reference/fees/fee-object). Sent when a fee for a charge to be paid in advance is created. You can use this information to collect the payment of the `pay_in_advance` fee. Useful for fintech companies that need to create a statement of transactions without invoicing.
</ParamField>

<ParamField path="subscription.started" type="data.object">
  [Subscription object](/api-reference/subscriptions/subscription-object). Sent when a subscription starts.
</ParamField>

<ParamField path="subscription.termination_alert" type="data.object">
  [Subscription object](/api-reference/subscriptions/subscription-object). Alert for imminent termination of subscriptions with set end dates, sent 45 days and 15 days prior (at fixed intervals).
</ParamField>

<ParamField path="subscription.terminated" type="data.object">
  [Subscription object](/api-reference/subscriptions/subscription-object). Sent when a subscription is terminated.
</ParamField>

<ParamField path="subscription.trial_ended" type="data.object">
  [Subscription object](/api-reference/subscriptions/subscription-object). Sent when the free trial is ended for a subscription.
</ParamField>

<ParamField path="subscription.usage_threshold_reached" type="data.object">
  [Subscription object](/api-reference/subscriptions/subscription-object). Sent when a progressive billing threshold has been crossed.
</ParamField>

## Wallets and prepaid credits

<ParamField path="wallet_transaction.updated" type="data.object">
  [Wallet transaction object](/api-reference/wallets/wallet-transaction-object). Sent when a wallet transaction is updated. For example, when wallet transaction is marked as settled.
</ParamField>

<ParamField path="wallet.depleted_ongoing_balance" type="data.object">
  [Wallet object](/api-reference/wallets/wallet-object). Sent when the ongoing balance is negative or equal to 0.
</ParamField>


# Product updates

New updates and improvements to Lago.

<Update label="November 2024">
  ## Roll your API key

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/changelog/images/20241122-roll-api-keys.png" />
  </Frame>

  Oops! Think your API key might be exposed, or just want to rotate it to stay safe? No worries—you don’t need to reach out to us. You can now quickly roll your key anytime in the Developer section.

  [Learn more](../guide/security/api-keys)

  ## Automatic Dunning: Payment reminders on autopilot

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/changelog/images/20241113-auto-dunning.gif" />
  </Frame>

  For businesses billing on usage, keeping payments timely is essential. That's why we're introducing **Automatic Dunning**—a hands-off way to manage overdue invoices and keep cash flow steady.

  With Automatic Dunning, you can **set up tailored reminder campaigns** for different customer groups. Once activated, **these campaigns run on autopilot**, sending scheduled email reminders for any unpaid invoices. Reminders will keep going until the payment is made or you adjust the settings.

  Automatic Dunning keeps your payment reminders on autopilot, so you can focus on what matters while your billing engine handles collections in the background.

  [Learn more](../guide/dunning/automatic-dunning)

  ## Customizable Rounding for usage metrics

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/changelog/images/20241113-rounding.png" />
  </Frame>

  Previously, usage rounding in Lago was limited to a default precision. Now, with **Customizable Rounding Rules**, you have full control over how usage-based metrics are rounded.

  Choose from these rounding options:

  *   **Ceil**: Always round up to the nearest integer.
  *   **Floor**: Always round down to the nearest integer.
  *   **Round**: Round to the nearest integer using standard rounding rules.

  Additionally, you can specify a **precision level**—positive or negative—allowing you to round usage to a set number of decimals.

  [Learn more](../guide/billable-metrics/rounding)

  ## Build any usage-Based Metric with SQL Expressions

  Previously, usage-based metrics in Lago were powered by a single field—ideal for simplicity but limited in flexibility. Now, we are giving you complete control with SQL Expressions.

  **With SQL Expressions, you can build metrics tailored to your needs**. Use advanced math operations, concatenations, rounding, and more to create precise, custom metrics that reflect your unique usage patterns.

  **Custom expressions allow you to define more advanced computation logic** by dynamically using any event field within your expression. Here are a few examples:

  *   **Concatenation:** `CONCAT(value1, '_', value2)`
  *   **Math operations:** `((value1 * value2) / value3)`
  *   **Rounding:** `ROUND(value1 / value2)`

  ```SQL SQL Expression example
  CEIL((event.properties.ended_at - event.timestamp) / 3600)
  ```

  [Learn more](../guide/billable-metrics/sql-expressions)

  ## Cascade plan editions to overridden subscriptions

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/changelog/images/20241113-cascade-plans-edits-to-overridden-sub.png" />
  </Frame>

  You have now the flexibility to decide whether changes made to the parent plan should automatically cascade to all overridden subscriptions.
  For instance, if you add a new charge to the parent plan, it will immediately reflect in the overridden subscriptions, ensuring that all pricing updates are seamlessly applied across your entire customer base while maintaining the flexibility of custom pricing.

  [Learn more](../guide/plans/overview#editing-plans)

  ## Sync billing data to HubSpot

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/changelog/images/20241105-sync-billing-data-hubspot.jpg" />
  </Frame>

  With Lago’s new integration, you can now seamlessly sync billing data in real time to HubSpot. By connecting your Lago account to HubSpot, you’ll enable the following:

  1.  **Customer Creation**: Automatically create Contacts or Companies in HubSpot based on your Lago customer data.
  2.  **Invoice Syncing**: Real-time invoice sync to a HubSpot custom object named `LagoInvoices`.
  3.  **Subscription Syncing**: Real-time subscription sync to a HubSpot custom object named `LagoSubscriptions`.

  [Learn more](../integrations/crm/hubspot)

  ## Quote in Salesforce CPQ, bill in Lago!

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/changelog/images/20241105-sync-billing-data-salesforce-cpq.jpg" />
  </Frame>

  Our enhanced Salesforce package now enables you to use Salesforce CPQ for quoting leads and customers.
  **Once a quote is approved and signed, it automatically triggers a real-time subscription in Lago**.
  No need for separate processes—your sales team can directly create subscriptions from validated quotes within Salesforce.

  [Learn more](../integrations/crm/salesforce-cpq)

  ## Dynamic pricing

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/changelog/images/20241105-dynamic-pricing.png" />
  </Frame>

  Do your prices change dynamically based on a provider or complex in-house calculations?
  Here are some real-life use cases:

  *   🤖 AI companies: prices fluctuating based on real-time models cost
  *   🏦 Fintech: matching prices to live market data
  *   📱 Telco/CPaaS: adjusting costs to fluctuating carrier rates

  We've heard you, and we're excited to introduce Dynamic Pricing for this!
  You can now set a charge model as Dynamic and send the event amount directly through each event. No more headaches trying to manage interchange fees or fluctuating custom prices.

  [Learn more](../guide/plans/charges/charge-models/dynamic)
</Update>

<Update label="October 2024">
  ## Credit note on prepaid credit invoices

  Refund your customers who purchased prepaid credit in no time!
  You can now process refunds for prepaid credit bought within Lago directly, without needing to engage your payment provider.
  Lago takes care of the refund through its credit note module, enabling you to initiate the refund to the payment provider and automatically void the prepaid credit in the active wallet according to the wallet’s refund status.

  [Learn more](/guide/credit-notes.mdx)

  ## Customer Portal complete rework

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/changelog/images/20241031-customer-portal-rework.jpg" />
  </Frame>

  We’ve **completely reworked the Customer Portal**. You can now embed the portal URL to display in real-time **plans and usage information**, **wallet data**, **customer info**, and **invoice lists**.

  Additionally, your end customers can take actions directly within the portal, such as **adding prepaid credits** and **updating their customer info**—all automatically synced with your Lago back office.

  **Cherry on top?** We’re offering the new Customer Portal **for free** to all users, including those on our open-source plan.

  ## Usage ingestion sources

  <Frame>
    <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/changelog/images/20241031-ingest-usage-custom-sources.jpg" />
  </Frame>

  Premium ingestion sources for metering and usage consumption are now **generally available**.
  Instead of using the basic API, you can leverage dedicated connectors to ingest data directly from sources like **AWS S3**, **AWS Kinesis**, **Kafka**, **MongoDB**, and **Azure**.
  Most connectors support ingestion rates of **over 15,000 events per second** (compared to 1,000 via the basic REST API).

  For custom ingestion connectors, please contact the Lago team.

  [Learn more](/guide/events/metering-source)

  ## Customer type

  <Frame>
    <img src="https://cdn.prod.website-files.com/63569f390f3a7ad4c76d2bd6/670e3492b8af7e403998631d_670e348652aa9119b8d40ec5_Mail%252038%2520Company%2520vs%2520Individual.png" />
  </Frame>

  Users can specify whether the customer is a company or an individual by setting the customer type.

  By default, if no customer type is specified, customers are created without a defined type and you will need to assign one manually.

  [Learn more](/guide/customers/customer-management#companies-vs-individuals)

  ## Send tax invoices

  <Frame>
    <img src="https://cdn.prod.website-files.com/63569f390f3a7ad4c76d2bd6/670e342075003c7364903b11_670e34092f78a79d6fac4518_Tax%2520invoice.png" />
  </Frame>

  Lago invoices are now fully compliant with local legislation in Australia, Indonesia, New Zealand and the United Arab Emirates.

  In those countries, it is mandatory to emit "Tax Invoices" accord to specific rules. This can now be handled with Lago.

  ## Retrieve all events using the API

  Users can now retrieve and filters all events using the API. The endpoint also allows for filtering by:

  *   `code`
  *   `external_subscription_id`
  *   `timestamp_from`
  *   `timestamp_to`

  [Learn more](/api-reference/events/list-events)
</Update>

<Update label="September 2024">
  ## Anrok integration ✨

  <Info>✨ This feature is only available via a paying add-on. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  We have developed an integration with Anrok to make tax management easier. This native integration allows you to automatically update your invoices with tax amounts sourced directly from Anrok.

  *   Lago sends the customer's address, tax identifier (if applicable), and the relevant product ID to calculate the appropriate tax for each line item
  *   Anrok calculates the tax for the invoice and returns the data to Lago, which is used to update the invoice with accurate tax information
  *   Lago synchronizes updates for voided and disputed invoices, as well as any credit notes created, ensuring that your records remain up to date

  This integration ensures compliance with international tax regulations by calculating taxes for US & non-US obligations, like VAT.

  [Learn more](/integrations/taxes/anrok#mapping-items-between-lago-and-anrok-mandatory)

  <Frame>
    <img src="https://cdn.prod.website-files.com/63569f390f3a7ad4c76d2bd6/66ead609693bf0b7c4c33372_66ead603a7be86769eb0ce97_mail-36-lago-anrok.png" />
  </Frame>

  ## Precise amount for fees

  Lago now allows you to retrieve the precise (ie. non rounded) amount on the fee object. Before only the rounded `amount_cents` was available.

  To use the precise fee amount, you can use the `precise_amount` field.

  [Learn more](/api-reference/fees/fee-object)

  <Frame>
    <img src="https://cdn.prod.website-files.com/63569f390f3a7ad4c76d2bd6/66ead5ba17d9844835539533_66ead5b4097b06391471f487_mail-36-fee-precise-amount.png" />
  </Frame>

  ## Progressive billing ✨

  <Info>✨ This feature is only available via a paying add-on. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  Progressive billing, also known as threshold billing, automatically triggers an invoice when a customer's cumulative usage reaches predefined thresholds.

  This method ensures that customers cannot exceed certain usage limits without ensuring payment is received, reducing the risk of unpaid services or fraud.

  You can setup 2 types of threshold:

  *   Step-based threshold: invoices are generated when the lifetime usage of a subscription reaches a defined threshold. You can set an unlimited number of thresholds, each with a specific amount and a unique name
  *   Recurring threshold: this threshold determines what happens after the final step-based threshold is reached. (For example, after the last threshold, Lago will automatically bill \$100 each time the lifetime usage increments by that amount)

  [Learn more](/guide/plans/progressive-billing#progressive-billing)

  ## Skip empty invoices generation

  Users can now decide whether or not to issue \$0 invoices (ie. empty invoices). By default, empty invoices are generated. You can change this setting at the organisation level.

  When creating a customer, it takes by default the configuration of the organization for this specific field.

  However, you can decide to override this information for a specific customer. Why? You might have customers who need to receive an invoice each month, even if the total amount is 0.

  [Learn more](/guide/invoicing/overview#finalize-empty-invoices)

  <Frame>
    <img src="https://cdn.prod.website-files.com/63569f390f3a7ad4c76d2bd6/66ead69e8d93cffff76e3ca1_66ead69b3927db5ea498e4cc_mail-36-skip-0-invoice.png" />
  </Frame>

  ## Filter and export invoices

  Users can now filter the list of invoices (e.g. by currency, customer, issuing date, etc.) and the filtered list can then be exported from the user interface.

  Two export options are available:

  *   Standard, including the list of invoices and invoice amounts (i.e. one row per invoice)
  *   Advanced, including the list of fees (i.e. one row per fee, so multiple rows per invoice if the invoice includes multiple fees)

  The list is automatically emailed to the requester in a CSV file.

  [Learn more](/guide/invoicing/export)

  <Frame>
    <img src="https://cdn.prod.website-files.com/63569f390f3a7ad4c76d2bd6/66d590ad4898ed6c465f308a_66d5905057e9afbb44b530e6_filter-export-invoices.png" />
  </Frame>

  ## Wallet transaction metadata

  When creating a wallet transaction via API, you can add metadata to store additional information (e.g. source of the transaction).

  This information is not displayed in the user interface.

  [Learn more](/api-reference/wallets/wallet-transaction-object)
</Update>

<Update label="August 2024">
  ## Invoicing options for wallet top-ups

  When creating a new wallet for a customer, users can choose to generate invoices for credit purchases either:

  *   As soon as the wallet transaction is created
  *   Only when payment is successful, which avoids generating invoices for transactions that have not been finalized

  These options are also available for automatic and manual top-ups (see `wallet_transaction.invoice_requires_successful_payment`).

  [Learn more](/guide/wallet-and-prepaid-credits/overview#invoicing-after-successful-payment-option)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/66b9a5353bcc3c82de50005a_66b9a4d0e366be520e901864_topup-invoice-if-paid.png" />
  </Frame>
</Update>

<Update label="July 2024">
  ## API changes (v1.7.0)

  As announced a few months ago, we have updated the event ingestion process and removed deprecated API fields. Changes include:

  **1. Replacing groups with filters**

  The new dimension system based on filters allows users to create billable metrics with more than two dimensions, and makes it easier to create charges based on custom event properties. The old dimension system based on groups has been permanently removed from the Lago API ([see all changes](/guide/migration/migration-to-v1.2.0#1-transition-from-group-to-filters)).

  **2. Marking `external­_subscription­_id` as mandatory for events**

  Events that only include `external­_customer­_id` are no longer taken into account when aggregating usage ([learn more](/guide/migration/migration-to-v1.2.0#2-mandatory-external-subscription-id-field-in-event-payloads)). This change will streamline the event validation process and enable real-time billing capabilities.

  **3. Removing deprecated API fields**

  For the sake of clarity and to preserve the quality of the API, we've deprecated several legacy fields ([see full list](/guide/migration/migration-to-v1.2.0#3-deprecated-fields)).

  [Learn more](/guide/migration/migration-to-v1.2.0)

  ## Invoicing options for instant charges ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  For charges paid in advances, Lago offers three invoicing options:

  *   An invoice can be issued for each event
  *   An invoice that only includes paid fees can be issued at the end of the billing period
  *   No invoices (users only rely on the `fee.created` webhook)

  [Learn more](/guide/plans/charges/invoiceable-vs-noninvoiceable)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/669df9a12a27751fcf4c176c_regroup-fees.png" />
  </Frame>

  ## Xero integration ✨

  <Info>✨ This feature is only available via a paying add-on. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  We have developed a Xero integration to make accounting easier. Available features include:

  *   Connecting a Lago account to a Xero account via OAuth
  *   Mapping Lago objects such as billable metrics, plans, coupons, wallet credits and taxes to Xero items
  *   Real-time synchronization of customer accounts
  *   Real-time synchronization of invoices
  *   Real-time synchronization of credit notes
  *   Real-time synchronization of payments

  [Learn more](/integrations/accounting/xero)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/669e5787323898dab0e6c0d5_xero-integration.png" />
  </Frame>

  ## Link checkout

  For card payments processed through integration with Stripe, users can enable the Link option. Link automatically fills the customer's payment information for faster checkout.

  [Learn more](/integrations/payments/stripe-integration#link)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/669a69858d650ff02d0d8acc_link-stripe.png" />
  </Frame>

  ## Overview of customer billing

  The customer view features a new billing section, including:

  *   Gross revenue (i.e. total amount billed to the customer)
  *   Total overdue (i.e. total amount of invoices that are past their due date)

  This improvement is the first step toward dunning management (coming soon).

  [Learn more](/guide/customers/customer-management#monitor-the-customers-billing-status)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/669a6c88553775726dbfbe32_overdue-balance.png" />
  </Frame>

  ## NetSuite integration ✨

  <Info>✨ This feature is only available via a paying add-on. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  We have developed a NetSuite integration to make accounting easier. Available features include:

  *   Connecting a Lago account to a NetSuite account via OAuth
  *   Mapping Lago objects such as billable metrics, plans, coupons, wallet credits and taxes to NetSuite items and tax items
  *   Real-time synchronization of customer accounts
  *   Real-time synchronization of invoices (and sales orders)
  *   Real-time synchronization of credit notes
  *   Real-time synchronization of payments

  [Learn more](/integrations/accounting/netsuite)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6690fd220e725bf64cae8573_netsuite.png" />
  </Frame>

  ## Shipping address

  In addition to the customer's billing address, users can add a shipping address. This information can be useful when the applicable tax rates are determined through integration with a tax management provider (e.g. Anrok).

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6691072102427ae629bba52f_shipping-address.png" />
  </Frame>

  ## Overdue invoices

  If an invoice is not marked as paid once its due date has passed, it is considered to be overdue. The billing system will then send a webhook message to notify the organization that issued the invoice (see `invoice.payment_overdue`).

  [Learn more](/api-reference/webhooks/messages#payment-overdue)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6691054994914e08de22b597_overdue-invoices.png" />
  </Frame>

  ## Custom pricing ✨

  <Info>✨ This feature is only available via a paying add-on. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  For companies whose aggregation and pricing models cannot be reproduced using standard functions, our team can inject a custom code snippet into the billing application.

  This feature allows users to implement advanced billing rules based on custom logic, which can be very useful when migrating from an in-house billing system.

  [Learn more](/guide/plans/charges/charge-models/custom-price)

  ## Okta SSO ✨

  <Info>✨ This feature is only available via a paying add-on. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  Users can sign up and log in to their Lago account through Okta single sign-on (SSO), which enables a better experience and ensures that the identity provider remains the system of record for authenticating users.

  [Learn more](/guide/security/sso#okta-sso)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/669001f17a346a946b55b65d_okta-sso.png" />
  </Frame>

  ## Hiding subscription fees at zero

  We have modified the invoice template and introduced new rules for subscription fees:

  *   If `amount_cents` is zero for the subscription fee and there are no other fees (e.g. usage-based charges or commitment) in the invoice, the subscription fee will appear on the PDF invoice
  *   If `amount_cents` is zero for the subscription fee and there are other fees in the invoice, the subscription fee will not be displayed on the PDF invoice

  ## Role-based access control (RBAC) ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  With the RBAC feature, organizations can ensure that each member only has access to the information and actions required to perform their job duties.

  There are three roles available on the Lago platform:

  *   Admin: full access to all views and actions (usually assigned to billing engineers and managers)
  *   Account Manager: can manage customer accounts and subscriptions (suitable for sales and success teams)
  *   Finance & Analyst: mostly view-only, with the ability to manage invoices and credit notes

  [Learn more](/guide/security/rbac)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/66904bd5019fdc202e474c2d_rbac.png" />
  </Frame>

  ## Recurring wallet top-ups ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  Users can define rules to automatically trigger wallet top-ups, based on two methods:

  *   Fixed: a predefined number of credits is added to the customer's wallet
  *   Target: credits are added to the customer's wallet to reach a predefined balance

  There are also two trigger options:

  *   Interval: weekly, monthly, quarterly or yearly top-ups, with a custom start date
  *   Threshold: the top-up is triggered when the ongoing balance of the wallet reaches a predefined minimum threshold

  [Learn more](/guide/wallet-and-prepaid-credits/wallet-top-up-and-void#setup-recurring-top-ups)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/669054b3caad7a097a442a2a_recurring-top-up.png" />
  </Frame>

  ## Webhook messages for wallets

  Lago now sends webhook messages when:

  *   A wallet transaction is created (see `wallet_transaction.created`)
  *   The status of a wallet transaction is updated (e.g. when a pending transaction is settled - see `wallet_transaction.updated`)
  *   When the ongoing balance of the wallet is zero or less than zero (see `wallet.depleted_ongoing_balance`)

  [Learn more](/api-reference/webhooks/messages#wallets)

  ## Void wallet credits

  The endpoint `POST /wallet_transactions` includes a new function to void credits, which are immediately deducted from the balance of the customer's wallet.

  This action can also be triggered via the user interface.

  [Learn more](/api-reference/wallets/top-up)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/668fdfe2eb597ec66f9e6be9_void-wallet-credits.png" />
  </Frame>
</Update>

<Update label="April 2024">
  ## Filters for billable metrics

  We have made changes to our dimension system and replaced metric groups with filters. This new feature offers greater flexibility as:

  *   Users can create as many filters as needed (they are no longer limited to two dimensions)
  *   Users can define specific rates based on very granular filter combinations (e.g. online card payments with Visa cards, offline card payments with Amex cards, etc.)

  [Learn more](/guide/plans/charges/charges-with-filters)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/662910db994a499707b7a2a7_filters-charge.png" />
  </Frame>

  ## Google SSO

  Users can sign up and log in to their Lago account through Google single sign-on (SSO), which enables a better experience and ensures that the identity provider remains the system of record for authenticating users.

  [Learn more](/guide/security/sso#google-sso)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/66253cad310d9303b8409d12_google-sso.png" />
  </Frame>

  ## Improved trial period

  When the subscription fee of a plan is paid in advance and the plan includes a trial period, the first invoice was initially generated when the subscription started. Following feedback from the Lago Community, we have modified this logic to generate the first invoice at the end of the free trial.

  [Learn more](/guide/plans/plan-model#the-trial-period-optional)

  ## Payment disputes

  If a payment dispute is reported as lost by the payment provider, Lago will provide `invoice.payment_dispute_lost_at` and send the webhook message `invoice.payment_dispute_lost`.

  This feature is available via integrations with Stripe and Adyen.

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/66254d35eec50942aebf62f4_disputes.png" />
  </Frame>

  ## Upcoming API changes (v1.2.0)

  We have released a new version of Lago with exciting new features, but also API changes likely to affect our users' workflows.

  **1. Replacing groups with filters**

  We have developed a new dimension system that offers greater flexibility. Filters allow users to create billable metrics with more than two dimensions, and make it easier to create charges based on custom event properties.

  However, this feature introduces changes to a number of objects, including `billable_metric`, `plan`, `fee` and `customer_usage`. In addition, the endpoint to retrieve billable metric groups will be deprecated ([see all changes](/guide/migration/migration-to-v1.2.0#1-transition-from-group-to-filters)).

  **2. The external subscription ID becomes mandatory for events**

  In order to develop real-time billing capabilities, we need to streamline our validation process. We have therefore decided to make `external_subscription_id` mandatory when sending events via the Lago API.

  Events that only include `external_customer_id` will no longer be taken into account when aggregating usage ([learn more](/guide/migration/migration-to-v1.2.0#2-mandatory-external-subscription-id-field-in-event-payloads)).

  **3. Deprecation of API fields**

  For the sake of clarity and to preserve the quality of the API, we are going to deprecate several legacy fields ([see full list](/guide/migration/migration-to-v1.2.0#3-deprecated-fields)).

  **Timeline**

  We will maintain the current API logic until July 9, 2024. After this date, previous versions will no longer be supported. We kindly ask our users to update their integration before that day to avoid any potential breaking change.

  [Learn more](/guide/migration/migration-to-v1.2.0)

  ## Minimum plan commitment ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  When creating a plan, defining a commitment ensures a minimum invoice amount for the billing period.

  This minimum is calculated at the end of the period, taking into account the subscription fee and all usage-based charges. If the total amount invoiced is less than the minimum commitment, Lago will automatically apply a true-up fee.

  The default commitment can be overridden when assigning the plan to a customer.

  [Learn more](/guide/plans/commitment)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6625421c94bb460b0cdb4fd3_plan-commitment.png" />
  </Frame>
</Update>

<Update label="March 2024">
  ## ACH and BACS payments

  Lago's native integration with Stripe supports two new payment methods:

  *   ACH Direct Debit for customers with a US bank account
  *   BACS Direct Debit for customers with a UK bank account

  [Learn more](/integrations/payments/stripe-integration#supported-payment-methods)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/65f00f034ccf549951bebeb6_stripe-ach-bacs.png" />
  </Frame>

  ## Grouping of charges

  It is possible to group charges on the invoice according to a custom attribute. When creating a charge based on the standard pricing model, users can define one or several `grouped_by` attributes that will then be used to provide information on the distribution of usage.

  For a customer who has sent thousands of API requests, for instance, we could display the breakdown of usage based on the `workspace_id` to which each request is linked.

  [Learn more](/guide/invoicing/overview#custom-invoice-grouping)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/65f00c3f4853f8925c5f62b4_grouped-by.png" />
  </Frame>

  ## Updated Salesforce package ✨

  <Info>✨ This feature is only available via a paying add-on. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to the Salesforce CRM integration.</Info>

  This new package allows users to initiate actions in Lago without leaving the Salesforce interface. It includes two customizable flows:

  1.  Ability to automatically create Lago customers from Salesforce accounts
  2.  Ability to automatically create Lago subscriptions from Salesforce opportunities, including the option to override existing plans

  [Learn more](/integrations/crm/salesforce-crm#iii-actions-from-salesforce-to-lago)
</Update>

<Update label="February 2024">
  ## Payment link for a specific invoice

  We have added a new endpoint to generate checkout URLs for specific invoices.

  This feature is available via integrations with Stripe and Adyen. It allows users to collect payments in countries where payment methods cannot be saved for future use.

  [Learn more](/api-reference/invoices/payment-url)

  ## Wallet balance in (near) real-time ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  In addition to the invoiced balance, which represents the credit available in the wallet after the last invoice has been finalized, wallets include an ongoing balance, which takes into account the customer's current usage and taxes.

  The ongoing balance gives an overview of the credit available in the wallet in near real-time, as it is updated every 5 minutes.

  [Learn more](/guide/wallet-and-prepaid-credits/overview#real-time-wallet-balance)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/65c3bec9ca11bfc9501f67f3_real-time-balance.png" />
  </Frame>
</Update>

<Update label="January 2024">
  ## Edit draft invoices ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  When an invoice is in draft (i.e. during the grace period), fees can be modified via the user interface. Users can either:

  *   Overwrite the total number of units, in which case Lago will automatically recalculate the fee based on the pricing model associated with the charge
  *   Overwrite the number of units and unit price, in which case Lago will automatically recalculate the fee based on this information

  [Learn more](/guide/invoicing/grace-period#edit-a-specific-fee)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/65c3bbab15766bd2c4ef9184_edit-draft-invoice.png" />
  </Frame>

  ## Multiple PSP accounts

  If an organization has multiple accounts with the same PSP (e.g. US Stripe account and EU Stripe account) they can all be connected to Lago. Users can then select the most appropriate account to process payments for each customer.

  [Learn more](/integrations/introduction#payments-integrations)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/65b7b4d1022173be6cd5c96f_multi-psp.png" />
  </Frame>

  ## Batch endpoint

  Events can now be sent in batches using the new `/events/batch` endpoint. Each API call may include up to 100 events.

  [Learn more](/api-reference/events/batch)

  ## Disabling emails for invoices without fees

  To avoid sending too many notifications to customers, we have deactivated emails for invoices without fees.

  Although invoices with `"fees_amount_cents": 0` are no longer sent to customers by email, they are still available in the database and user interface.

  [Learn more](/guide/emails#email-scenarios)
</Update>

<Update label="December 2023">
  ## Custom invoice numbering

  We have made invoice numbering more flexible, with three elements:

  *   Prefix that can be customized
  *   Dynamic sequence, either based on sequential customer IDs, or based on year and month (i.e. YYYYMM)
  *   Sequential number of the invoice (i.e. 001, 002, 003, etc.)

  [Learn more](/guide/invoicing/overview#invoice-numbering)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/658c3af9eb231c5e672f5c8f_invoice-numbering.png" />
  </Frame>

  ## EU tax management

  Lago's EU tax detection feature allows users to check customers' tax identification numbers through integration with the European VAT Information Exchange System (VIES), and to automatically assign them a tax rate based on their country.

  [Learn more](/integrations/taxes/lago-eu-taxes)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/658c3f1197589af28f53f1e0_lago-eu-tax-mgt.png" />
  </Frame>

  ## Unit prices

  PDF invoices now include details of charges for each pricing model (e.g. for graduated pricing, we display the number of units and unit price for each tier).

  This information is also available in the invoice object (see `invoice.fees.amount_details`).

  [Learn more](/api-reference/invoices/invoice-object)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/658c47c497589af28f586160_fee-unit-price.png" />
  </Frame>

  ## Automatic wallet top-ups ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  Customer wallets can be topped up automatically according to predefined rules:

  *   Based on a time interval (e.g. weekly, monthly, etc.)
  *   Based on a threshold (e.g. when the wallet balance is less than or equal to \$10)

  [Learn more](/guide/wallet-and-prepaid-credits/wallet-top-up-and-void#setup-recurring-top-ups)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6570a3dfd5171330e5dc2126_wallet-top-ups.png" />
  </Frame>
</Update>

<Update label="November 2023">
  ## Event validations

  We have added an `events.errors` webhook message to notify users when some of the events ingested in the last hour are invalid.

  Possible errors include:

  *   Invalid billable metric code
  *   Missing aggregation property
  *   Missing group key

  [Learn more](/api-reference/webhooks/messages#event-ingestion)

  ## Regenerate checkout links

  When a customer wants to update their payment method, or when a checkout link has expired, users can generate a new checkout URL on demand through the Lago API.

  This action is available for all our native payment integrations.

  [Learn more](/api-reference/customers/psp-checkout-url)

  ## Custom success URL

  When setting up one of our native payment integrations, users can define the URL to which customers should be redirected after completing the checkout process. Custom URLs can only be added via the user interface.

  [Learn more](/integrations/introduction#payments-integrations)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/65538c396760d1cb5c7e7d0f_success-url.png" />
  </Frame>

  ## Default currency

  The organization's currency can be defined in the settings of the account or via API. It is used as the default currency when creating new objects, such as plans and add-ons, and to display information on dashboards.

  [Learn more](/api-reference/organizations/update)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/65538fc86913d3aab0bdf794_default-currency.png" />
  </Frame>

  ## Helm chart updates

  We have released a new version of the Lago Helm Charts to facilitate on-premise deployment.

  [Learn more](https://github.com/getlago/lago-helm-charts)
</Update>

<Update label="October 2023">
  ## Integration with Salesforce CRM ✨

  <Info>✨ This feature is only available via a paying add-on. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to the Salesforce CRM integration.</Info>

  With the new Salesforce CRM integration, Lago data is automatically synced with Salesforce.

  Users can access their customers' subscriptions, invoices and credit notes directly in their CRM application.

  [Learn more](/integrations/crm/salesforce-crm)

  ## Removal of event validations

  We are currently upgrading our infrastructure and setting up a new event ingestion system. As part of this project, we have decided to remove the validations that were automatically performed when ingesting events through the Lago API.

  This means that the API no longer returns error messages when events include incorrect parameters (e.g. wrong billable metric code, subscription not found, `transaction_id` already exists, etc.).

  ## Retrieve a subscription

  We have added a new endpoint to allow users to retrieve a specific subscription via the Lago API, using the `external_id` of the subscription.

  [Learn more](/api-reference/subscriptions/get-specific)

  ## Webhooks for subscription upgrades/downgrades

  When the plan associated with a subscription changes, Lago automatically notifies the user with two webhook messages:

  *   `subscription.terminated` to confirm the termination of the initial plan (includes `next_plan_code`)
  *   `subscription.started` to confirm the start of the new plan (includes `previous_plan_code`)

  [Learn more](/api-reference/webhooks/messages)

  ## Plan details

  In the Plans section of the app, users can now click one of their plans to see its details (i.e. name, code, interval, currency, subscription fee, usage-based charges, etc.) and also retrieve the list of subscriptions linked to the plan.

  In addition, in the customer view of the app, users can click one of the subscriptions assigned to their customer to see its details (i.e. status, start date, interval, currency, fees, charges, etc.).

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/652fa9d8bb0bdb53c30aea81_plan-details.png" />
  </Frame>

  ## Override plans ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  When assigning a plan to a customer, you can modify some attributes to create a custom plan. Editable fields include (but are not limited to):

  *   Currency
  *   Subscription fee
  *   Charge prices
  *   Minimum spending requirements
  *   Tax rates
  *   Invoice display names

  Details of the new plan will be available in the customer view.

  [Learn more](/guide/subscriptions/assign-plan#overriding-a-plan)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/652d5f42d17f781134b3f428_plan-override.png" />
  </Frame>

  ## Spanish locale

  ¡Hola a todos! The Spanish locale is now available on Lago.

  Users can select it as their organization's default language or as a customer's preferred language.

  [Learn more](/api-reference/resources/locales)

  ## Swedish locale

  Hej alla! The Swedish locale is now available on Lago.

  Users can select it as their organization's default language or as a customer's preferred language.

  [Learn more](/api-reference/resources/locales)

  ## Display names on invoices

  When creating or updating a plan, users can define custom display names for subscription and usage-based charges, which will be printed on the PDF files generated by Lago.

  Display names can be defined via the user interface or the API (see `plan.invoice_display_name` and `charges.invoice_display_name`).

  [Learn more](/guide/plans/charges/overview#update-invoice-display-names)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/651fffd240c8227ee8ccaf83_invoice_display_name.png" />
  </Frame>

  ## Retrieve past usage

  We have added a new endpoint to retrieve past usage. When a billing period has ended, users can still retrieve usage data through `GET /customers/{external_customer_id}/past_usage`.

  Users must specify `external_subscription_id` and can filter results by `billable_metric_code`. They can also select the number of past periods for which they wish to retrieve usage data.

  [Learn more](/api-reference/customer-usage/get-past)
</Update>

<Update label="September 2023">
  ## LATEST aggregation

  `latest_agg` allows users to compute usage based on the last value received during the period for a billable metric.

  Consider the following example for the `storage` metric, where usage is aggregated based on the property `gb`:

  *   The first event includes 5 GB
  *   The second event includes 7 GB
  *   The third event includes 6 GB

  With `latest_agg`, at the end of the billing period, the total number of units used to calculate the fee will be 6, as it's the last value received.

  [Learn more](/guide/billable-metrics/aggregation-types/latest)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/650da517aba506f5de907e33_latest_agg.png" />
  </Frame>

  ## WEIGHTED SUM aggregation

  `weighted_sum_agg` allows users to compute usage based on a custom property and the time elapsed between two events (e.g. memory consumption measured in GB-seconds).

  Billable metrics based on this aggregation type can be metered or recurring, and are always billed at the end of the billing period.

  [Learn more](/guide/billable-metrics/aggregation-types/weighted-sum)

  ## Subscription end date

  When a subscription end date is set, the subscription is automatically terminated by Lago.

  A notification is sent to the user 45 days and 15 days before the subscription is terminated (see `subscription.termination_alert` webhook).

  If no end date is set for a subscription, it will renew automatically.

  [Learn more](/guide/subscriptions/assign-plan#subscription-end-date)

  ## Duplicate plans

  Users can duplicate an existing plan from the user interface to create a new plan with the same structure. They can then choose a name and a code for their new plan, and modify the parameters that differ from the original plan (e.g. interval, currency, charges, etc.).

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/650dad92cde93dce0f94e2dc_duplicate_plan.png" />
  </Frame>

  ## Edit dimensions

  When dimensions are defined for a billable metric, users can add/remove groups by modifying the corresponding code snippet via the user interface, or by updating the billable metric object via API.

  Changes to dimensions may affect all plans where the billable metric is listed as a charge.

  [Learn more](/guide/billable-metrics/filters)
</Update>

<Update label="August 2023">
  ## Default price for groups

  For billable metrics that include several [groups](/guide/billable-metrics/filters), when configuring their plans, users can set a default price that applies to all groups.

  The default price can be overwritten by setting a different price for a specific group.

  If the default price is not defined, it is automatically set to zero.

  [Learn more](/guide/invoicing/overview#custom-invoice-grouping)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/64edceea0edeebc0c927a55f_groups_default_price.png" />
  </Frame>

  ## Italian locale

  Ciao a tutti! The Italian locale is now available on Lago.

  Users can select it as their organization's default language or as a customer's preferred language.

  [Learn more](/api-reference/resources/locales)

  ## Minimum / Maximum per transaction ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  The percentage pricing model includes a new option for defining minimum and maximum prices per transaction.

  When applied, Lago adjusts the fees based on the `per_transaction_min_amount` and `per_transaction_max_amount` parameters.

  [Learn more](/guide/plans/charges#available-charge-models)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/64edd2e4d50ff59c5b723c4e_min_max_transaction.png" />
  </Frame>

  ## Webhook for subscriptions started

  We have added a new webhook message for subscriptions.

  When the status of a subscription switches to `active`, Lago automatically sends a `subscription.started` message.

  [Learn more](/api-reference/webhooks/messages)

  ## Graduated percentage pricing

  We have added a new graduated pricing model, which allows users to define prices based on a percentage of the number of units, and to add a flat fee for each tier (optional).

  [Learn more](/guide/plans/charges#available-charge-models)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/64e89f342b91415c55065d3d_graduated_percentage.png" />
  </Frame>

  ## Quarterly billing interval

  In addition to the weekly, monthly and yearly intervals, Lago `v0.44.1-beta` includes the new quarterly interval.

  When selected, all fees (i.e. subscription fee and charges) are billed every three months.

  [Learn more](/guide/plans/plan-model#plan-interval)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/64e0c3a5adf760339f515865_quarterly_interval.png" />
  </Frame>

  ## Webhook signatures

  When creating a webhook endpoint through the user interface or the API, you can choose between:

  *   The original `JWT` signature
  *   The new `HMAC` signature, which includes a shorter header

  Please refer to the guide to find out how to verify the webhook signatures.

  [Learn more](/api-reference/webhooks/format---signature)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/64dc879de79a172c36a2591c_webhook-signature.png" />
  </Frame>

  ## Taxes applied to add-ons

  Tax objects can now be used to define the default tax rate(s) associated with an add-on.

  When creating a one-off invoice, if there is no tax rate associated with the add-on, Lago will automatically select the tax rate defined at customer or organization level.

  The tax rate applied to the add-on can be modified at any time through the user interface or the API.

  [Learn more](/guide/invoicing/taxes#taxes-at-the-add-on-level)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/64dc8ef6dc475efb34be6f09_taxes-one-off-invoices.png" />
  </Frame>

  ## Net payment term

  The net payment term determines the number of days given to the customer to pay their invoice. It is calculated based on the date the invoice is finalized and displayed on the PDF file.

  When the net payment term is defined at the organization level, it applies to all customers by default. However, it can be overridden by the net payment term defined at the customer level.

  [Learn more](/guide/invoicing/net-payment-term)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/64d61160a4369260ee492462_net_payment_term.png" />
  </Frame>

  ## Taxes defined at plan and charge level

  In addition to the taxes defined at organization and customer level, users can select tax objects at plan and charge level.

  For subscription invoices, the tax hierarchy is as follows:

  1.  Taxes defined at **organization level** will apply to all fees (i.e. subscription and charges)
  2.  Taxes defined at **customer level** will take precedence over taxes defined at organization level and will apply to all fees (i.e. subscription and charges)
  3.  Taxes defined at **plan level** will take precedence over taxes defined at customer level and will apply to all fees (i.e. subscription and charges)
  4.  Taxes defined at **charge level** will take precedence over taxes defined at plan level but will only apply to the fee associated with the corresponding charge

  [Learn more](/guide/invoicing/taxes)
</Update>

<Update label="July 2023">
  ## Filter subscriptions by status

  We have added a new query parameter to the endpoint that allows users to retrieve subscriptions.

  By default, `GET /api/v1/subscriptions/` returns all active subscriptions. However, you can also retrieve pending, canceled and terminated subscriptions by using the `status` parameter.

  [Learn more](/api-reference/subscriptions/get-all)

  ## SEPA Direct Debit with Stripe

  Our native integration with Stripe now supports SEPA Direct Debit payments.

  When Stripe is defined as the default payment provider for a customer, you can select the authorised payment method(s): card, direct debit or both.

  Before initiating a payment intent, Lago will automatically check the customer's default payment method registered in Stripe.

  Kindly note, SEPA Direct Debit is only available for invoices denominated in euros (EUR).

  [Learn more](/integrations/payments/stripe-integration#payment-methods)

  ## Recurring and prorated charges

  When a billable metric is defined as [recurring](/guide/plans/charges#metered-vs-recurring-charges), the number of billing units at the end of the billing period is carried over to the next period. It is not reset to zero, as with metered metrics.

  Users can create recurring metrics based on `sum_agg` and `count_unique_agg`. They can also define whether the corresponding charges should be [prorated](/guide/plans/charges#prorated-vs-fully-billed-charges) (this option is only available for the standard and volume pricing models).

  <Info>ℹ️ Metrics based on `recurring_count_agg` have been automatically converted into `count_unique_agg` metrics with the attribute `"recurring": true`.</Info>

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/64c78b87721dcd020fb02e93_recurring_prorated_charge.png" />
  </Frame>

  ## Cancel pending subscriptions

  When a subscription is created with a subscription date in the future, its status is automatically set to `pending`.

  You can now cancel a pending subscription through the Lago API, using the following endpoint:
  `DELETE /api/v1/subscriptions/{external_id}?status=pending`

  [Learn more](/api-reference/subscriptions/terminate)

  ## Multiple webhook endpoints

  Webhook messages can be used to collect billing information and set up custom workflows. They are related to subscriptions, events, fees, invoices, payment providers and credit notes.

  You can now create up to five webhook endpoints to listen to Lago events.

  [Learn more](/guide/webhooks)

  ## Custom tax objects

  In the settings of their account, users can define the default tax rate that applies by default to all customers of their organization. This tax rate can then be overwritten at the customer level.

  Whether set at the organization level or the customer level, so far the tax rate used to calculate fees was simply indicated as "Tax" on invoices.

  To give users more flexibility, we've added the option to create several tax objects, which can then be assigned to the organization or specific customers (e.g. state sales tax, VAT, reverse charge, GST, etc.).

  [Learn more](/guide/invoicing/taxes)

  ## Stripe checkout URL

  When a new customer is successfully created through Lago's native integration with Stripe, the billing system sends a `customer.checkout_url_generated` webhook message.

  You can redirect your customer to the corresponding page to register their payment method, which will then be used to collect payment when a new invoice is issued.

  [Learn more](/integrations/payments/stripe-integration#stripe-checkout-storing-customers-payment-method-information)

  ## Tax identification number

  The [customer object](/api-reference/customers/object) and [organization object](/api-reference/organizations/organization-object) include a new `tax_identification_number` attribute. When a value is available for this attribute, it is automatically displayed on the PDF version of the next invoices.

  ## Integration with GoCardless

  Lago now offers native integration with [GoCardless](https://gocardless.com/), including (but not limited to):

  *   Ability to define GoCardless as the default payment provider for a customer
  *   Ability to automatically create Lago customers in GoCardless and retrieve their customer ID
  *   Ability to automatically collect payments via direct debit
  *   Ability to automatically update the status of an invoice depending on the payment status
  *   Ability to automatically resubmit failed payments with [GoCardless Success+](https://gocardless.com/solutions/success-plus/)

  To learn more about this integration, please [consult our guide](/integrations/payments/gocardless-integration)
</Update>

<Update label="April 2023">
  ## Minimum spend on charges ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  You can now define minimum spending requirements for usage-based charges.

  The minimum spend is defined as an amount excluding tax. If at the end of the billing period, your customer has spent less than the minimum, then Lago will automatically generate a true-up fee to compensate for the difference.

  Minimum spending requirements are defined when creating or editing plans, either through the user interface or the API.

  [Learn more](/guide/plans/charges#charge-spending-minimum)

  ## Coupons limited to specific metrics

  We have added a new option to the coupon settings: it is now possible to limit the application scope of a coupon to specific billable metrics.

  By default, coupons apply to all charges but when creating a new coupon, you can define the list of billable metrics to which the coupon applies.

  This feature is related to the `billable_metric_codes` attribute of the `coupon` object ([see API documentation](/api-reference/coupons/create)).

  Please refer to [the guide](/guide/coupons) for more information on coupons.

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d99a2c0c03ba2fc5401f1_coupons-bm-1c2ee68ef19c01172755b5f8a2df7a57.png" />
  </Frame>

  ## Reset password

  You can now reset your password via the user interface.

  On the login page, click "Forgotten password" to access the dedicated page where you can request a link to reset your password.

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d99855923b14e5744c2ad_reset-password-f3bf1adf1ab7196efb7818a6876e0597.png" />
  </Frame>
</Update>

<Update label="March 2023">
  ## Automatic emails ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  We are introducing a new built-in invoicing feature, which allows you to automatically send invoices and credit notes from Lago to your customers.

  The email template can be customized with the name, email address and logo of your organization, and will be sent in the customer's preferred language (or the default language defined in the settings of your account).

  For cloud users, Lago takes care of the SMTP setup. For users on the self-hosted version, the setup is described in the public documentation.

  [Learn more](/guide/emails)

  ## Customer billing portal ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  We have released the first version of our billing portal, which allows your customers to access their invoices.

  You can generate access links through the user interface or embed the customer portal into your application using our API and an iframe.

  [Learn more](/guide/customers/customer-portal)

  ## Invoice metadata

  After an invoice has been generated, you can add metadata to store additional information (e.g. custom ID, payment reference, etc.). This information will be included in the `invoice` object but will not be displayed on the PDF invoice.

  Invoice metadata can be managed via the user interface or the API.

  [Learn more](/guide/invoicing/invoice-metadata)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d9912609433d243c5394a_invoice-metadata-b13dd0c8879275b47474d90751c6d3ce.png" />
  </Frame>

  ## Customer metadata

  When creating or editing a customer, you can add metadata to store additional information (e.g. customer type, name of the account manager, etc.).

  Customer metadata can be displayed on invoices, and can be managed via the user interface or the API.

  [Learn more](/guide/customers/customer-metadata)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d98eba25357cc364d7601_customer-metadata-ca988533d02dd460cdd300c4a6e05967.png" />
  </Frame>

  ## Webhook logs

  The new webhook management system allows you to access the list of webhook messages sent by Lago and check their status. You can re-trigger a message that has failed through the user interface.

  To access the webhook logs:

  1.  Go to the **Developers** section via the sidebar
  2.  Open the **Webhooks** tab
  3.  Click on the webhook endpoint to see the list of messages

  [Learn more](/guide/webhooks)

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d98c95cae0642bcbfe06d_webhook-logs-4bb9abafa5c8ccc09b8f0416aae2adb1.png" />
  </Frame>
</Update>

<Update label="February 2023">
  ## Document translation

  PDF files including invoices and credit notes can be generated in different languages.

  The [default language](/guide/invoicing/download-invoices#translate-invoices) that is set at the organization level can be overwritten by the [customer's preferred language](/guide/customers/invoice-customer#preferred-language).

  In the API, the `document_locale` attribute determines the language of the documents.

  You can contribute to Lago's open-source project by helping us translate documents. The new language will then be added to the [list of supported locales](/api-reference/resources/locales) and available to the entire Lago Community.

  ## Update payment status

  You can now update the payment status of an invoice through the user interface.

  To do so:

  1.  Access the **Invoices** section
  2.  Find the relevant invoice
  3.  Click the ellipsis icon on the right
  4.  Click **Update payment status**
  5.  Select the new payment status
  6.  Click **Update status** to confirm

  This action can be performed [via the API](/api-reference/invoices/update) as well.

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d988e13539e399a78763c_payment-status-ui-05432db8f7ea894d3e94a33697d59375.png" />
  </Frame>

  ## Coupons limited to specific plans

  We have added a new option to the coupon settings: it is now possible to limit the application scope of a coupon to specific plans.

  By default, coupons apply to all plans but when creating a new coupon, you can define the list of plans to which the coupon applies.

  This feature is related to the `plan_codes` attribute of the `coupon` object ([see API documentation](/api-reference/coupons/create)).

  Please refer to [the guide](/guide/coupons) for more information on coupons.

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d984f67a4e10db11f906e_coupons-plans.png" />
  </Frame>
</Update>

<Update label="January 2023">
  ## Coupons that apply forever

  When creating a coupon, through the [user interface](/guide/coupons) or the [API](/api-reference/coupons/create), it is now possible to select the `forever` frequency.

  Coupons with the `forever` frequency apply to all subscription invoices, regardless of the number of subscription invoices generated in a given period.

  <Info>ℹ️ The value of the coupon is deducted from the amount of the invoice after tax. Coupons do not apply to add-ons or any other one-off charges.</Info>

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d97ecb648e82c370f81ad_coupons-forever.png" />
  </Frame>

  ## Search bar

  Tired of scrolling through an endless list to find the customer your are looking for? We understand that.

  We have added a search functionality to the user interface to make it easier to find metrics, plans, customers, invoices, etc.

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d9828b9891d90712245d2_search-bar.png" />
  </Frame>

  ## Payment retries

  We have added the ability to resend payments for collection.

  This new feature is available to all users:

  *   Through the user interface ([learn more](/guide/payments/payment-retries))
  *   Through the API ([learn more](/guide/payments/payment-retries))

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d979bec6a5cd21aa2945a_retry-payment.png" />
  </Frame>

  ## Grace period ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  If at the end of the billing period, you want to review the invoices before sending them to customers for payment, you can define a [grace period](/guide/invoicing/grace-period).

  During the grace period, invoices are in `draft` status and can be modified. Available actions include:

  *   **Adding usage records** by sending events with a `timestamp` within the relevant billing period
  *   **Applying coupons** to the customer's account
  *   **Adding credits** to the customer's wallet and credit note wallet

  When the grace period expires, invoices are automatically `finalized` (they can no longer be edited), which triggers the `invoice.created` [webhook](/api-reference/webhooks/messages). You can also finalize invoices manually.

  The organization's grace period applies to all customers by default, but it can be overwritten by the customer's grace period.

  ## Invoice list

  We have added a new **Invoices** section, which allows you to access the list of invoices.

  Invoices are filtered according to their status (i.e. draft or finalized) and according to their payment status (i.e. succeeded, pending or failed).

  The same filters can be applied when [retrieving invoices via the API](/api-reference/invoices/get-all).

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d971142f0800f8b954abc_invoice-list.png" />
  </Frame>

  ## Credit notes ✨

  <Info>✨ Lago may automatically generate a credit note when a subscription is upgraded or downgraded. However, only users with a premium license can manually generate credit notes via the user interface or the API. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  You can now use your Lago account to issue credit notes for subscription invoices and add-ons.

  Depending on the payment status of the invoice, you will be able to:

  *   **Refund the customer** (only for paid invoices)
  *   **Credit back the customer's account**

  Please refer to the [documentation](/guide/credit-notes) for more information on credit notes and credit methods.

  ## Timezones ✨

  <Info>✨ This feature is only available to users with a premium license. Please contact [hello@getlago.com](mailto:hello@getlago.com) to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

  You can now set the timezone of your organization in the settings of the app. To do so:

  1.  Access the **Settings** section via the side menu
  2.  In the **Organization** tab, you will see the current timezone (UTC by default)
  3.  Click **Edit**
  4.  Select a new timezone from the list
  5.  Click **Save timezone** to confirm

  It can also be set through the API using this [endpoint](/api-reference/organizations/update).

  The organization's timezone applies to all customers by default and determines when billing periods start and end (i.e. when invoices should be generated). It is also the reference timezone for most views and lists in the app.

  The organization's timezone can be overwritten by the customer's timezone ([learn more](/guide/customers/invoice-customer#bill-following-your-customers-timezone)).

  <Info>ℹ️ In the app, you can hover over any date with a dotted underline to see the reference timezones.</Info>
</Update>

<Update label="December 2022">
  ## Lago Open API

  We have developed an Open API to help you get started with Lago and make it easier to test our solution.

  Please refer to the [documentation](/guide/lago-open-api) to learn how to import the Lago Open API into Postman and create a new collection.

  Our [public repository](https://github.com/getlago/lago-openapi) is also available on GitHub.
</Update>

<Update label="November 2022">
  ## Apply several coupons

  You can now apply several coupons to a customer account.

  When several coupons are applied to a customer, they will be deducted according to the date on which they were applied: the coupon that was applied first will be deducted first.

  The remaining value / number of remaining periods for each coupon will be visible in the **Overview** tab of the customer view.

  You can also use `GET /api/v1/applied_coupons` to retrieve all coupons applied to a customer.

  ## Invoice details

  To review the invoice details through the user interface:

  1.  Go to the **Customers** section
  2.  Select a customer to open the customer view
  3.  Open the **Invoices** tab
  4.  Click the invoice to see its details

  On the details page, you can download the invoice in PDF format and copy the invoice ID through the **Actions** dropdown in the upper right corner.

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d92a996e93ed861bf238b_invoice-details.png" />
  </Frame>
</Update>

<Update label="October 2022">
  ## Integration with GoCardless

  Lago now offers native integration with [GoCardless](https://gocardless.com/), including (but not limited to):

  *   Ability to define GoCardless as the default payment provider for a customer
  *   Ability to automatically create Lago customers in GoCardless and retrieve their customer ID
  *   Ability to automatically collect payments via direct debit
  *   Ability to automatically update the status of an invoice depending on the payment status
  *   Ability to automatically resubmit failed payments with [GoCardless Success+](https://gocardless.com/solutions/success-plus/)

  To learn more about this integration, please [consult our guide](/integrations/payments/gocardless-integration).

  ## Subscription date

  It is now possible to set a start date in the past or in the future for a new subscription.

  Setting a start date in the past can be useful when migrating existing customers to Lago, while setting a start date in the future can be useful for scheduling upcoming subscriptions.

  For more information about the impact of the start date on the invoicing process, please refer to [the documentation](/guide/subscriptions/assign-plan#subscription-date).

  ## Dimensions for grouping events

  When creating a new billable metric, you can define dimensions that will be used to group events according to their properties.

  For example, if you want to charge your customers for compute capacity according to the cloud provider and server region, you can create a `compute` billable metric with two dimensions ([learn more](/guide/billable-metrics/filters)).

  Changes to the API include:

  *   Ability to add a `group` parameter with one or two dimensions when [creating](/api-reference/billable-metrics/create) or [updating](/api-reference/billable-metrics/update) billable metrics
  *   Ability to [retrieve the groups](/api-reference/billable-metrics/get-all-groups) associated with a billable metric
  *   Ability to add a `group_properties` parameter when [creating](/api-reference/plans/create) or [updating](/api-reference/plans/update) a plan
  *   Ability to retrieve [customer usage](/api-reference/customer-usage/customer-usage-object) by group
  *   New `lago_group_id` for fees (see [invoice object](/api-reference/invoices/invoice-object))

  ## Enhanced coupon model

  We have improved the coupon model to offer more flexibility.

  Changes include (but are not limited to):

  1.  Ability to define the value of a coupon as a fixed amount or percentage
  2.  Ability to create recurring coupons that apply over several billing periods
  3.  Ability to set an expiration date (i.e. date after which the coupon can no longer be redeemed)

  [Learn more](/guide/coupons)

  ## Customer currency

  It is now possible to define the currency at [customer](/api-reference/customers/object) level.

  The currency associated with each customer was previously defined by the currency of the plan assigned to the customer. This logic prevented users from assigning a coupon or an add-on to a customer before creating a subscription.

  When creating a new customer via the user interface or the API, you can now select the currency associated with the customer. If the currency is not defined at customer level, it will be determined by the first object assigned to the customer (i.e. currency of the plan, add-on, coupon, or wallet).

  <Info>⚠️ Once an object has been assigned to the customer (i.e. plan, add-on, coupon, or wallet), the currency associated with the customer cannot be changed.</Info>

  ## Error management

  We have refactored the error management system to give more visibility to API users.

  The `message` attribute for errors has been replaced with `code` and `error_details`, which provide more information about the errors. There are several codes associated with each error.

  For example, when creating a new billable metric, the API may return `"error": "Unprocessable entity"` with the code `value_is_mandatory` for the `name` field (i.e. the name of the billable metric is missing).

  Please refer to the [documentation](/api-reference/intro) available for each endpoint for more information on error codes.
</Update>

<Update label="September 2022">
  ## Invite members

  You can now invite your teammates to join your Lago account.

  To add a new member via the user interface:

  1.  Go to the **Settings** section of the app
  2.  Open the **Members** tab
  3.  Click **Invite a member** on the right
  4.  Enter the email address of your teammate
  5.  Click **Generate invitation link** to confirm
  6.  Copy the invitation link to share it with your teammate

  Invitation links have no expiration date. When your teammate clicks the link, they can choose their password and then access the account.

  You can remove a member by clicking the **bin icon** on the right of the list of members.

  <Info>ℹ️ All members have the same role and permissions.</Info>

  ## Overwrite plans

  If after a negotiation phase, you need to create a custom plan for an important customer, you can use the 'overwrite' feature, available through the user interface.

  This feature allows you to create a new plan from an existing one, in order to adjust the plan model and charges according to your business needs.

  Overwriting a plan has no impact on the original plan or existing subscriptions.

  [Learn more](/guide/subscriptions/assign-plan#overwriting-a-plan)

  ## Recurring count

  Companies with fair and transparent pricing models are often praised by customers. If you are considering implementing seat-based pricing for instance, the `reccuring_count` aggregation is exactly what you need.

  This new aggregation type allows you to push events for persistent units.

  Consider the following example:

  > Your customer is on a monthly plan and adds a new user to their account on September 15th, so you generate an event that corresponds to one billing unit.
  >
  > At the end of September, Lago will automatically create a prorated charge for this user, based on the number of days of activity (i.e. from September 15th to September 30th).
  >
  > This billing unit will remain valid until you generate another event to remove it. For instance, if your customer deletes the user on October 22nd, Lago will create another prorated charge for the period October 1st to October 22nd.

  Consult [our guide](/guide/billable-metrics/recurring-vs-metered) to learn more about persistent units.

  ## External IDs

  We are introducing changes to the API that will make it easier to manage subscriptions:

  *   For the [creation of new subscriptions](/api-reference/subscriptions/assign-plan), `subscription_id` and `unique_id` will be removed and replaced with `external_id` (required)
  *   For all other endpoints, `subscription_id` will be replaced with `external_subscription_id`

  This will allow you to operate via the API using your own identifiers and save you the trouble for storing our IDs.

  In addition to this, for consistency purposes:

  *   For the [creation of new customers](/api-reference/customers/create), `customer_id` will be replaced with `external_id`
  *   For all other endpoints, `customer_id will be replaced with `external\_customer\_id\`

  These changes will come into effect on **September 8, 2022**.

  Please [get in touch](https://www.getlago.com/slack) with our team if you have any questions.
</Update>

<Update label="August 2022">
  ## Volume charge model

  The new volume charge model allows you to create a tiered pricing structure and then calculate a unit price that applies to all units depending on total volume.

  It is similar to the graduated charge model, except that only one price tier applies at the end of the billing period.

  Please refer to [the guide](/guide/plans/charges#charge-models) and [API documentation](/api-reference/plans/create) for more information.

  ## Anniversary dates for subscriptions

  When assigning a plan to a customer, you can now choose whether the subscription should be renewed at the beginning of the period or on its anniversary date.

  For instance, if a monthly plan is assigned to a customer on August 10th and you choose to align the billing cycle with the anniversary date of the subscription, the customer will be billed every 10th of the month.

  With [the API](/api-reference/subscriptions/assign-plan), you can use the `billing_time` attribute to choose your preferred option. If not provided, Lago will base the subscription on calendar periods.

  [Learn more](/guide/subscriptions/assign-plan#billing-cycles)

  ## Free units for the percentage charge model

  We have released an enhanced version of the percentage charge model, including:

  *   Ability to define free units based on the number of events (e.g. first 3 events are free)
  *   Ability to define free units based on the total amount (e.g. first \$500 are free)

  Please refer to the [documentation](/guide/plans/charges#charge-models) for more information.

  ## Multiple plans

  It is now possible to assign multiple plans to a customer (e.g. if your customer needs to create several workspaces on your platform, you can link a plan to each workspace).

  To help differentiate each plan, you can add display names that will appear in the user interface and on invoices.

  Kindly note that:

  1.  All plans must be denominated in the same currency
  2.  You must now specify the `subscription_id` for each event or create batch events

  [Click here to see the documentation](/guide/subscriptions/assign-plan#multiple-plans)

  ## Tracking & Analytics

  To help us better understand your needs, we have added a tracking module to the self-hosted version of Lago.

  Data analytics will help us improve the quality of our product and performance of the API.

  As the privacy of our users is of paramount importance, we will not collect any personal information about your customers or the amount of your invoices, and you can opt out at any time.

  [Learn more](/guide/self-hosted/tracking-analytics)

  ## Go client

  We have added a new API client to make it easier for Go users to set up their billing system with Lago.

  [Click here to see the documentation](/api-reference/intro)
</Update>

<Update label="July 2022">
  ## App version

  It is now possible to check the version of the Lago application you are using.

  Click on of your `organization's name` in the top-left corner of the user interface to see the app version currently in use.

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d800242f0800f8b7ada30_app-version.png" />
  </Frame>

  ## Current usage

  Good news for those who follow closely the consumption of their customers. You can now track the current billing usage of your customers either from the UI or from the API.

  **To access this Usage tab:**

  1.  Access your list of **customers**
  2.  Select a specific customer that is **already linked to a subscription**
  3.  Access the **usage** tab
  4.  Get a complete view of **usage-based consumption** that is going to be billed on the next invoice

  On top of that, you can fetch the current usage of a customer directly from the API. To do so, you can access the following endpoint `GET /api/v1/customers/:customer_id/current_usage`

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d7fb119ef4234068c5b9a_current-usage.png" />
  </Frame>

  ## PDF invoices

  Lago will generate a PDF file for each new invoice.

  You can download invoices via the user interface or the API and can also modify some of the elements included in the invoice template.

  Full documentation [available here](/guide/invoicing/download-invoices).

  ## New API endpoints

  We like our users when they use our nice and clean UI, but we also love when they use our API. One of the usecase could be to use Lago as a white-labeled solution.

  Here is the full list of endpoints we have just released:

  **Billable metrics**

  *   Create a billable metric `POST /api/v1/billable_metrics`
  *   Update a billable metric `PUT /api/v1/billable_metrics/:code`
  *   Destroy a billable metric `DELETE /api/v1/billable_metrics/:code`
  *   Fetch a specific billable metric `GET /api/v1/billable_metrics/:code`
  *   Fetch all billable metrics `GET /api/v1/billable_metrics?per_page=2&page=1`

  **Plans**

  *   Create a plan `POST /api/v1/plans`
  *   Update a plan `PUT /api/v1/plans/:code`
  *   Destroy a plan `DELETE /api/v1/plans/:code`
  *   Fetch a specific plan `GET /api/v1/plans/:code`
  *   Fetch all plans `GET /api/v1/plans?per_page=2&page=1`

  **Coupons**

  *   Create a coupon `POST /api/v1/coupons`
  *   Update a coupon `PUT /api/v1/coupons/:code`
  *   Destroy a coupon `DELETE /api/v1/coupons/:code`
  *   Fetch a specific coupon `GET /api/v1/coupons/:code`
  *   Fetch all coupons `GET /api/v1/coupons?per_page=2&page=1`

  **Add-ons**

  *   Create a add\_on `POST /api/v1/add_ons`
  *   Update a add\_on `PUT /api/v1/add_ons/:code`
  *   Destroy a add\_on `DELETE /api/v1/add_ons/:code`
  *   Fetch a specific add\_on `GET /api/v1/add_ons/:code`
  *   Fetch all add\_ons `GET /api/v1/add_ons?per_page=2&page=1`

  **Current usage**

  *   Get the current usage of a specific customer `GET /api/v1/customers/:customer_id/current_usage`

  **Organization**

  *   Update the information of your organization `PUT /api/v1/organizations`
</Update>

<Update label="June 2022">
  ## Integration with Stripe Payments

  Lago now offers native integration with Stripe, including (but not limited to):

  *   Ability to create Lago customers in Stripe automatically and retrieve their customer ID
  *   Ability to define Stripe as the default payment provider for a customer
  *   Ability to generate payment intents automatically
  *   Ability to update the status of an invoice depending on the payment status
  *   Ability to receive a webhook when a payment fails

  To learn more about this integration, please [consult our guide](/integrations/payments/stripe-integration).

  ## Weekly plan interval

  When setting up a plan, you can select the weekly interval to define a weekly billing period.

  The plan interval applies to the subscription and charges, which means that:

  *   For plans that must be paid in advance, the subscription fee is invoiced at the beginning of the week
  *   For plans that are paid in arrears, the subscription fee is invoiced at the end of the week
  *   Usage is calculated at the end of each week

  The week starts on Monday and ends on Sunday. If the customer's subscription starts in the middle of the week, the fees will be applied on a pro-rata basis.

  ## Invoice monthly charges for a plan paid yearly

  Before the release of this feature, usaged-based features (charges) were following the plan period. If the plan period was invoiced yearly, the charges were invoiced yearly.

  It's now possible to **invoice billable metrics on a montly basis** for a plan billed yearly. The base amount of the plan will be invoice yearly (in-arrears or in-advance), but your usage based features will be invoiced on a monthly basis.

  **To do so:**

  1.  Access a **Plan**
  2.  Define a plan **yearly**
  3.  Price **additional charges** from your billable metrics
  4.  Turn `on` the toggle for **applying charges monthly**

  By switching on, **all the charges** will be invoiced monthly even if the plan is yearly.

  <Info>ℹ️ The last invoice is gathering both the subscription and the usage-based charges</Info>

  ## Events list

  You are now able to view all the ingested events sent from your application to Lago. We called this feature `Events list` because it makes the event ingestion easier and more understandable.

  1.  Access the `Developer` sidebar item
  2.  Click the `Events` tab
  3.  Take a look at the latest events ingested

  <Info>ℹ️ If an event you sent is not shown in the UI, it means that it has not been ingested by Lago</Info>

  This events list is also helpul to warn you for 2 specific cases:

  1.  **Warning 1** - The event code is not related to an existing billable metric
  2.  **Warning 2** - The property sent does not match the aggregation property defined in your billable metric

  <Frame>
    <img src="https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/649d7caf57c468e53266577a_events-list.png" />
  </Frame>

  ## Add-ons

  Add-ons are now available on Lago. Create add-ons to apply one-time fees (e.g. setup fee, one-time purchase, etc.) and generate the corresponding invoices instantly.

  Full documentation [available here](/guide/one-off-invoices/create-add-ons).
</Update>

<Update label="June 3, 2022">
  ## Pay-as-you-go template

  We've added a new template to our collection: [click here](https://www.getlago.com/resources/templates/algolia) to learn how to replicate Algolia's pay-as-you-go pricing.

  It's a great starting point for companies whose pricing fully depends on usage, such as cloud service providers and API companies.

  With Lago, you can adapt this template to your products and services, using some of our most popular features, including the ['sum' aggregation type](/guide/billable-metrics/aggregation-types) and the [package charge model](/guide/plans/charges#charge-models).

  ## Coupons

  Introducing coupons, a new feature that allows you to offer discounts to your customers.

  Full documentation [available here](/guide/coupons).
</Update>

<Update label="May 2022">
  ## Subscription changes

  You can now modify the subscription assigned to a customer through the user interface.

  To learn how to upgrade or downgrade a subscription and how it affects billing, please refer to the documentation.

  ## Package pricing for charges

  It is now possible to apply a [package pricing model](/guide/plans/charges#charge-models) to a charge. To do so:

  1.  Select an existing plan (or create a new one)
  2.  Add a charge
  3.  Select the package pricing model

  This new pricing model allows you to apply a flat fee to a range of units. The price will be fixed for the entire range, regardless of the number of units consumed by the customer during the billing period.

  ## Percentage charge model

  Inside the **plan**, when creating a charge, you can now select the **percentage charge model**.

  This feature is useful for industries willing to take a `% + fixed fee` out of a usage-based features (for banking or charity industry, for instance). These fees are applied on the *units to be charged* (e.g. the aggregation result of your billable metric).
</Update>


# About Lago



## 1. What is Lago?

[Lago](https://www.getlago.com/) is the leading open-source pricing solution focused on complex billing: multi-product/geographies, transactional, usage-based, subscription hybrids, etc, chosen by unicorns like Mistral (AI, \$640M raised at \$6 billion valuation), Accel-backed Swan (Embedded banking), Together.ai (AI, \$102.5M raised at \$1.25 billion valuation) or Groq (AI, \$300M raised at \$2.5 billion valuation).

Lago is API-first, the most loved billing solution on Github, and was voted Product of the day week, and month on Product Hunt.

Lago raised a total of [\$22M of funding](https://techcrunch.com/2024/03/14/lago-a-paris-based-open-source-billing-platform-banks-22m/) from investors including Y Combinator, FirstMark Capital, SignalFire, [Meghan Gill](https://www.linkedin.com/in/meghanpgill/), who has led the monetization efforts of MongoDB for 14 years, [Romain Huet](https://www.linkedin.com/in/romainhuet/), former head of Developer Relations at Stripe - now leading OpenAI developer experience, and [Clément Delangue](https://www.linkedin.com/in/clementdelangue/), CEO of AI open platform Hugging Face.

<iframe src="https://ghbtns.com/github-btn.html?user=getlago&repo=lago&type=star&count=true&size=large" frameborder="0" scrolling="0" width="150" height="30" title="GitHub" />

## 2. What does Lago do?

Lago helps businesses calculate how much their end-users need to pay, and make sure they’re paid.
This includes, but is not limited to:

*   Managing subscriptions
*   Metering consumption, or usage (e.g., for a telco provider: the number of minutes of a call ; for an electricity provider: the number of kwH used)
*   Generating and sending invoices
*   Triggering and tracking payments
*   Managing customers’ accounts

**Features overview:**

<CardGroup cols={2}>
  <Card title="Real-time usage metering" href="https://www.getlago.com/products/metering">
    Lago’s event-based architecture provides a solid foundation for building a
    fair pricing model that scales with your business.
  </Card>

  <Card title="Flexible plan configuration" href="https://www.getlago.com/products/plans">
    Lago supports all pricing models. Create pay-as-you-go and hybrid plans in
    no time with our intuitive user interface or API.
  </Card>

  <Card title="Coupons and discounts" href="https://www.getlago.com/products/coupons">
    Create engaging marketing campaigns and increase conversion with coupons
    that customers can redeem to get a discount.
  </Card>

  <Card title="Coupons and discounts" href="https://www.getlago.com/products/coupons">
    Create engaging marketing campaigns and increase conversion with coupons
    that customers can redeem to get a discount.
  </Card>

  <Card title="Add-ons and one-off invoices" href="https://www.getlago.com/products/add-on">
    Lago allows you to create one-time charges that are invoiced on the fly.
  </Card>

  <Card title="Invoices generation" href="https://www.getlago.com/products/invoicing">
    Depending on the configuration of your plans, Lago automatically calculates
    what each customer owes you and generates invoices.
  </Card>

  <Card title="Prepaid credits" href="https://www.getlago.com/products/prepaid-credits">
    Unlock recurring revenue opportunities for pay-as-you-go pricing models with
    Lago’s prepaid credit features.
  </Card>

  <Card title="Integrations" href="https://www.getlago.com/integrations">
    Lago Billing takes integration to the next level, seamlessly integrating
    with every aspect of your business operations.
  </Card>

  <Card title="Instant charges" href="https://www.getlago.com/premium-features/instant-charges">
    Charge customers instantly while retaining the freedom to choose whether or
    not to generate an invoice for the transaction.
  </Card>

  <Card title="Customer portal" href="https://www.getlago.com/premium-features/customer-portal">
    Effortlessly integrate the customer portal into your application, providing
    your customers with seamless access to detailed usage information and
    invoice data.
  </Card>

  <Card title="Spending minimums" href="https://www.getlago.com/premium-features/spending-minimum">
    Take control of your billing process by establishing minimum spending limits
    for charges. With our platform, you can easily define the minimum amount
    customers must meet for a usage-based component.
  </Card>

  <Card title="Email invoices" href="https://www.getlago.com/premium-features/email-invoices">
    Providing a seamless integration of email communication with the billing
    engine, allowing businesses to send professional invoices directly to their
    customers' inbox.
  </Card>

  <Card title="Grace periods" href="https://www.getlago.com/premium-features/grace-periods">
    Have the flexibility to make adjustments to customers' usage, even after the
    billing cycle has ended. Fine-tune and modify usage details, ensuring that
    you have complete control over your invoicing.
  </Card>

  <Card title="Billing timezones" href="https://www.getlago.com/premium-features/timezones">
    Simplify international billing. Bill your customers according to their
    respective timezones.
  </Card>

  <Card title="Credit notes and refunds" href="https://www.getlago.com/premium-features/credit-notes-refunds">
    Unlock customer satisfaction with credit notes issuance and customer
    refunds. Streamline your operations and foster trust by handling credit
    notes and refunds through our UI and API.
  </Card>
</CardGroup>

Check our documentation [here](https://docs.getlago.com/guide/introduction/welcome-to-lago), for more information.
Reproduce Notion, Slack, or Stripe’s pricing in a few clicks with our templates [here](https://www.getlago.com/resources/templates/all).

## 3. What is Lago origin story?

Lago was founded in 2021 by Anh-Tho and Raffi, who were among the earliest employees at Qonto.com – a \$5B B2B neobank. They led Qonto's revenue growth from pre-product to Series D, and built and scaled the monetization system that took the company from 0 to \$100M+ of revenue.
A fun fact was that when Raffi pitched the idea of Lago to Romain (a senior billing engineer at Qonto), he told him “no way”, and said he did want to quit his position at Qonto but he would “NEVER touch a billing system again”.
Step by step, Raffi managed to convince him he could channel this energy and experience to make sure fewer engineers would need to relive the billing nightmares he had to endure. And it worked!

At Qonto, they would always underestimate the engineering nightmare billing would create, and learned the hard way about the side effects: delayed launches at best, billing errors, resulting in churning users, and a growing “billing engineering” team that not only was expensive, but very hard to retain. The worst was that at some point, the “pricing strategy” nearly switched to “what’s the easiest option to implement”, rather than “what’s the best for the company”.
Raffi and Anh-Tho, and the founding Lago team then spent a lot of time carefully analyzing why no one had solved this huge problem yet, as they thought solid companies like Stripe or Chargebee had partially addressed it.

That’s how they built our conviction on the open-source and “platform” approach of Lago, to not be another “buy billing” option, but rather a “Lego '' that engineers build with to create their tailored monetization stack.

## 4. Does it work with my stack?

Yes. Lago is agnostic and can be used via:

*   Our no-code interface, see it in action [here](https://youtu.be/dXnoMRetsr4)
*   Our [API](https://doc.getlago.com/api-reference/intro)
*   Our native integrations: Segment, Hightouch, Stripe Payments, Adyen, Salesforce, and many others, [here](https://www.getlago.com/integrations)
*   One of our [backend libraries](https://doc.getlago.com/api-reference/intro) covering the main programming languages and tools
    You can use Lago with your stack, whatever it is.

## 5. Is this supported properly?

Lago is a well funded project with thousands of stars on [Github](https://github.com/getlago/lago), in [very active development](https://github.com/getlago/lago-api/graphs/commit-activity), by our [core team](https://www.getlago.com/about-us) and our active community.

Additionally, we have strong uptime performance ([99,99%+ uptime](https://status.getlago.com/uptime/klj713fz3fcy)) and \<10 min median response time across support channels.


# About the software



## 1. How popular is the software?

Lago has thousands of users, thousands of stars on Github and great investors.
Lago is the most popular open-source repository solving for billing on Github, to give you a point of reference, the second most popular one was started ten years ago, Lago caught up fast!
It has been chosen by companies like:

*   [Mistral.ai](http://Mistral.ai) – the open source genAI model provider, which raised more than \$600M with top VC ([see here](https://techcrunch.com/2024/06/11/paris-based-ai-startup-mistral-ai-raises-640-million/?guccounter=1)).
*   [Together.ai](http://Together.ai) – the leading decentralized AI cloud provider, backed by Kleiner Perkins and Nvidia ([see here](https://techcrunch.com/2023/11/29/together-lands-102-5m-investment-to-grow-its-cloud-for-training-generative-ai/))
*   [Groq](https://groq.com/) – the startup building AI-chip for fast inference, which raised more than \$640M from top VC ([see here](https://techcrunch.com/2024/08/05/ai-chip-startup-groq-lands-640m-to-challenge-nvidia/))
*   [Juni](https://www.juni.co/) – the fintech company that develops a banking app for e-commerce.
*   [Swan](https://swan.io) – the leading European Banking-as-a-Service (BaaS), backed by Accel and Creandum.

and many more.
To hear firsthand experiences from our users, explore Lago's  [customer stories](https://www.getlago.com/customers/stories) and our [love wall](https://shoutout.io/lago).

## 2. Is the software updated regularly?

We release new versions every 2-3 weeks, our team is working relentlessly to improve the product.
Sign up to our newsletter, or follow us on [Linkedin](https://fr.linkedin.com/company/getlago) or [X](https://twitter.com/getlago?lang=en) (fka Twitter).
Our past product updates are [here](https://www.getlago.com/resources/updates).

## 3. How secure is Lago?

Keeping your data secure is critical to how Lago operates. Lago is SOC 2 Type 2 compliant. SOC 2 compliance ensures the secure storage and transmission of data. Type 2 compliance tests the design and effectiveness of the systems over a long period of time.

To protect access to and transmission of your data, Lago supports Single Sign-On (SSO) and Role-based access control (RBAC). SSO allows you to centrally manage your access and RBAC policies define how users interact with Lago, giving you the chance to minimize security vulnerability.

Learn more about security at Lago [here](https://getlago.com/docs/guide/security/rbac).

## 4. How is this different from the other billing tools?

A lot of companies continue building billing in-house, even if it means building systems that engineers hate to build, let alone maintain.
Lago has been conceived to address complex billing use cases, with  a unique open-source approach, solving for:

*   Transparency: you can inspect our code, have an overview on our pull requests, github issues, what our users say and how they use Lago.
*   Control: you can opt for the convenience of Lago Cloud (our hosted solution) or choose the total control that our on-premise deployment offers: keep your data within your own system, and keep a direct access to all your usage, billing and payment data  in your own infrastructure, with the highest level of granularity.
*   Extensibility and connectivity: because engineers understand our code and infrastructure better.

Lago is the only open source metering and usage-based billing solution. A lot of closed source (aka ‘SaaS’) solutions exist (e.g., Stripe Billing, Zuora) but they require you to send your data to third-parties, to blindly trust a Chargebee‘black box’ with your most critical internal system (billing / revenue) and they take a cut on your revenue. We have put together these [product comparisons](https://www.getlago.com/resources/compare/compare-home) if you want to go further.

There are multiple open source billing offerings. However, Lago is the only open source software that gives you:

1.  Real-time event-based usage metering
2.  Subscription billing
3.  Hybrid plans, mixing subscription and consumption (e.g., a usage-based billing plan that requires a recurring minimum spend per month)
4.  A full fledge API to automate ‘self-serve/product-led’ plans, and an intuitive no-code user interface to configure ‘custom/enterprise’ plans
5.  Additional features including: instant charges, modular couponing, spending minimums, grace periods, etc

## 5. I have a home-made billing infrastructure. How is Lago useful?

Billing is indeed much harder and costly for engineers than it might initially seem.

When getting started, it seems pretty straightforward – you decide on a price, and customers pay you. But as your business grows, things get trickier. It's like managing a puzzle where the pieces keep changing. You have to deal with dates, handle plan upgrades, track usage, avoid charging twice, remind customers to pay, and navigate the tax maze (we have written some posts on this topic [here](https://www.getlago.com/blog/why-billing-systems-are-a-nightmare-for-engineers) and [here](https://www.getlago.com/blog/the-4-biggest-problems-with-homemade-billing-systems)).

Lago is an open source metering and billing API tailored for usage-based pricing. Our API and architecture are open, so you can embed, fork and customize them as much as your pricing and internal processes require.

If you are interested, you can [get started here](https://www.getlago.com/get-started) or [book a demo](http://getlago.com/book-a-demo).

## 6. Can Lago handle high volume processing?

Lago is designed for usage-based billing and high-volume data processing. Its engine is able to handle hundreds of thousands events per second, whether they come in the form of logs or back-end events. Our infrastructure is made to scale to billions of events per month if needed. For more details, we have written about our infrastructure [here](https://github.com/getlago/lago/wiki/Using-Clickhouse-to-scale-an-events-engine).

## 7. I’m an AI company. How is Lago helpful?

Engineering teams in AI companies should be 100% focused on monetizing, not getting bogged down by [billing nightmares](https://news.ycombinator.com/item?id=31424450).

That's where Lago, with its open-source metering and billing engine, comes in. Lago has already been chosen by leading AI companies such as [Mistral](https://mistral.ai/fr/), [Together.ai](http://Together.ai), [Groq.com](http://Groq.com), or [Cerebrium](https://www.cerebrium.ai/), for instance.

Lago’s infrastructure handles hundreds of thousands events per second and makes it easy to offer market-practices pricing features like per-token pricing, prepaid credits, real-time consumption monitoring and progressive billing.

Use one of our templates to replicate the pricing of [OpenAI](https://getlago.com/docs/templates/per-token/openai) or [Mistral](https://getlago.com/docs/templates/per-token/mistral).


# Community



## 1. What’s the community like?

Lago Community thrives through the active engagement of 6.6K+ users and developers, making it the largest and fastest-growing billing community on GitHub (see [here](https://github.com/getlago/lago)). It serves as the central hub where users and developers can seek support, request features and contribute to the ongoing enhancement of Lago's product.
You can also join hundreds of billing and pricing professionals in our [Slack Community](https://www.getlago.com/slack).

## 2. How can I contribute?

There are many ways to contribute to the Lago community. You can:

*   Share your expertise by answering questions on the Lago Community ([Join our Slack](https://www.getlago.com/slack))
*   Write blog posts or tutorials about Lago
*   Participate in Lago surveys and user interviews
*   Contribute to the Lago codebase (learn more [here](https://github.com/getlago/lago/blob/main/CONTRIBUTING.md))
*   Report bugs or suggesting improvements ([here](https://github.com/getlago/lago/blob/main/CONTRIBUTING.md))

For instance, our community played a pivotal role in introducing the "[Latest](https://docs.getlago.com/guide/billable-metrics/aggregation-types/overview)" aggregation type to Lago's product. Additionally, we regularly receive translation contributions from users in languages such as Italian, Spanish, and Norwegian.

Thanks to valuable contributions from our users, our community continues to grow stronger!

## 3. Can I suggest new features?

Yes. Lago warmly welcomes feature suggestions. Your ideas are valuable to us. You can suggest new features [here](https://getlago.canny.io/feature-requests). We will carefully review and prioritize highly requested ones, providing regular updates on their progress.


# Deployment



## 1. Is this hard to set up?

Lago is easy to set up, you can run our app in a few clicks by downloading our [Docker image](https://doc.getlago.com/guide/self-hosted/docker).
If you have any questions, or want access to our [premium features and/or our cloud version (paying)](https://www.getlago.com/pricing), reach out via [Slack](https://www.getlago.com/slack) or send an email to [hello@getlago.com](mailto:hello@getlago.com); we'll get back to you shortly.

## 2. Can I self-host?

Yes. Lago’s self-hosted version can be deployed on any infrastructure. We provide detailed instructions on [how to self-host Lago](https://docs.getlago.com/guide/self-hosted/docker).

## 3. How do I deploy?

There are three options:

1.  Lago Self-hosted:

*   Self-hosting the open-source product - Free, and self-serve [here](https://doc.getlago.com/guide/self-hosted/docker)
*   Self-hosting the premium product - Reach out [here](https://docs.google.com/forms/d/e/1FAIpQLSfKwXdwe3jIpPJuPs2Nmkw_3GqoUOEP1YxQ3B6frYfGgYJ11g/viewform?usp=send_form)

2.  Lago Cloud, with either US or EU hosting - There are only a few spots available to use this product at the moment, so we’ll ask you a couple of questions first, reach out [here](https://docs.google.com/forms/d/e/1FAIpQLSfKwXdwe3jIpPJuPs2Nmkw_3GqoUOEP1YxQ3B6frYfGgYJ11g/viewform?usp=send_form)
3.  Hybrid hosting: for Enterprise customers, Lago also offers cloud-prem or Virtual Private Cloud (VPC) deployments options

## 4. Can I get it live with my favorite hosting option?

See our instructions to deploy Lago’s open source product [here](https://doc.getlago.com/guide/self-hosted/docker).
Want to set it up differently? (Raise an issue)([https://github.com/getlago/lago/issues](https://github.com/getlago/lago/issues)) in the repo.


# General



## 1. Is billing that hard for engineers?

Yes. Billing is indeed much harder for engineers than it might initially seem. Imagine you're starting a business, and you want to charge your customers for your products or services. At first, it seems pretty straightforward – you decide on a price, and customers pay you. But as your business grows, things get trickier. It's like managing a puzzle where the pieces keep changing. You have to deal with dates, handle plan upgrades, track usage, avoid charging twice, remind customers to pay, and navigate the tax maze (see more [here](https://www.getlago.com/blog/why-billing-systems-are-a-nightmare-for-engineers)).

For example, deciding how often to charge your customers for subscriptions and charges might sound simple, like choosing between weekly, monthly, or yearly billing. But it's more complex than it appears. You also need to factor in things like leap years, offering free trial periods, and deciding how to handle pro-rata pricing. And if you ever decide to switch from billing based on 'anniversary' dates to calendar dates, that adds even more complexity to the mix.

At Lago, we've adopted a radical approach – we're building an open source billing API for product-led SaaS. Our API and architecture are open, so that you can embed, fork and customize them as much as your pricing and internal processes require.

If you're interested, you can [get started here](https://www.getlago.com/get-started) or [book a demo](http://getlago.com/book-a-demo).

## 2. How is Lago different from Stripe? Can Lago replace it?

Lago is an open source metering and billing solution, whereas Stripe primarily focuses on payment processing.

Stripe offers 21 products with separate fees (see more [here](https://www.getlago.com/blog/we-crunched-the-fees-of-stripes-21-products)), including Stripe Billing and Stripe Invoicing.
Lago can replace Stripe for some services such as billing, invoicing and potentially [more](https://www.getlago.com/blog/calculating-stripe-mrr-is-difficult), but it does not process payments directly. Businesses using Lago will need a separate payment processor. Lago calculates how much you should charge a user and when, and sends this information to your chosen payment gateway(s) (Lago is agnostic) for the actual payment processing.

See detailed comparison of Stripe Billing vs. Lago [here](https://www.getlago.com/resources/compare/lago-vs-stripe).

## 3. Is Lago cheaper than Stripe?

Stripe Billing will cost you 0.5% (and up to 0.8%) of your transaction volume, on top of Stripe Payments (starts at 2.9% + \$0.30 per successful card charge). With the full vendor lock-in of Stripe, you might stack dozens of fees that are directly impacting your own revenue. Once again, Stripe has 21 products and each of them has their own pricing (see more [here](https://www.getlago.com/blog/we-crunched-the-fees-of-stripes-21-products)).
Lago offers a forever-free open source solution for small businesses, allowing access to fundamental billing features. Besides, Lago provides Enterprise plans with access to premium features listed [here](https://www.getlago.com/pricing).

See detailed comparison of Stripe Billing vs. Lago [here](https://www.getlago.com/resources/compare/lago-vs-stripe).

## 4. How is Lago different from Chargebee?

Chargebee is not designed for usage-based billing. Lago is.

Lago is designed for usage-based pricing models, providing a high level of flexibility and support complex usage-based scenarios. Chargebee supports standard usage-based models (e.g. \$20 per user) but may not be flexible enough for businesses that need support for complex usage-based pricing models (e.g., PayPal's per-transaction pricing). Chargebee limits the maximum number of usages that can be recorded for a subscription is 5,000, over its lifetime.

Lago has no rate limit for usage-based billing events, allowing for high volume processing. Chargebee has a rate limit of 100 simultaneous requests per minute, which could prevent you from sending granular usage when you start scaling your number of customers.
Additionally, Lago, being an open source solution, offers complete transparency, allowing engineers to audit its code and even build on top of it, which Chargebee does not allow.

See detailed comparison of Chargebee vs. Lago [here](https://www.getlago.com/resources/compare/lago-vs-chargebee).

## 5. Is Lago cheaper than Chargebee?

Chargebee offers two services including billing and retention with separate fees. For billing:

*   Starter plan: No flat fee, with the first \$250K of cumulative billing included; 0.75% on billing thereafter. This plan includes basic billing features.
*   Performance plan: \$599 monthly flat fee for up to \$100K of monthly billing; 0.75% on billing thereafter. This plan offers access to some advanced features.
*   Enterprise plan: Custom pricing.

Lago offers a forever-free open source solution for small businesses, allowing access to fundamental billing features. Besides, Lago provides Enterprise Plans with access to premium features, as listed [here](https://www.getlago.com/pricing).

See detailed comparison of Chargebee vs. Lago [here](https://www.getlago.com/resources/compare/lago-vs-chargebee).

## 6. Can Lago be used by non-tech users?

Yes. Lago is a developer-first product with an intuitive interface. All actions in Lago can be performed via the API or the user interface, making Lago accessible to both tech-savvy and non-technical users alike.

For **Engineers**: Lago is Developer-first and API-first, offering high flexibility and ability to build on top of it. Lago can handle a high volume of events and works seamlessly with your existing tools.

For **Product managers**: Lago can adapt to any pricing model, and our easy-to-use interface lets non-technical teams manage billing without developer assistance. You can retrieve billing data for integration to your BI tools. You can also use it to trigger automations and implement alerting as needed.

For **Finance leaders**: Lago streamlines invoicing by automating charge calculations, supports various pricing plans, and helps track payments. Lago ensures the invoicing and cash collection process under your control. For instance, check who paid their invoices in a glance to improve cash collection. It also integrates billing data into your tools for better revenue insights.


# Pricing



## 1. Is Lago free?

Lago offers a forever-free open source solution offering access to fundamental billing features. Besides, Lago also offers paying plans with access to premium features listed [here](https://www.getlago.com/pricing).

## 2. How is your pricing structured?

Our pricing is structured in packages that are tailored to specific company stages: early, scaling, or more on the enterprise side.

We don’t take a cut on revenue, as we don’t think it’s a pricing strategy that can be worthwhile in the long term.

We’re willing to grow with our customers sustainably (if they are successful, we are successful too) so we have included a usage-based dimension (e.g., number of events ingested, invoices generated, or active customers) in our packages

Contact us at [hello@getlago.com](mailto:hello@getlago.com) to discuss what features and usage volumes work best for your company.

## 3. Can I self-host the Premium features?

Yes. Lago offers Enterprise plans with access to premium features listed [here](https://www.getlago.com/pricing). You have the flexibility to choose between cloud hosting or self-hosting options.

Please reach out via [Slack](https://lago-community.slack.com/ssb/redirect) or [hello@getlago.com](mailto:hello@getlago.com) for further details.

## 4. Can I have a free trial for Lago Premium?

You can use and/or try Lago forever-free product by downloading our self-hosted and open source product [here](https://doc.getlago.com/guide/introduction/welcome-to-lago). We unfortunately do not offer free trials for our premium plans (cloud or self-hosted).

In specific cases, our Solution Engineering team can organize ‘proofs of concepts’. Reach out via [Slack](https://www.getlago.com/slack) or [hello@getlago.com](mailto:hello@getlago.com) if you need help testing Lago.


# Product features



## 1. Does Lago support prepaid credits?

Yes. Prepaid credits are a great way to give customers better spend visibility and facilitate payment collection in advance.

To prepay for usage with lago follow this simple steps:

1.  Create a new wallet for prepaid credits;
2.  Assign a value for each credit (eg. 1 credit equals 1\$);
3.  Specify the number of credits to purchase; and
4.  Configure recurring top-up rules based on real-time consumption (threshold or interval top-ups)

See a real-life example of prepaid credits with Mistral [here](https://docs.getlago.com/templates/per-token/mistral#step-3-prepay-usage-with-credits).

## 2. Which payment methods does Lago support?

Lago is agnostic and enables you to connect with any payment providers. Lago is already natively integrated with several payment providers ([see here](https://docs.getlago.com/guide/payments/overview)).

## 3. Does Lago support invoicing?

Yes. Without charging a percentage of billings, every plan includes built-in invoicing automation with native invoice generation.

Lago enables you to issue invoices and send them to your customers via email. Lago offers advanced invoicing features, allowing you to customize invoice templates, and to include [customer metadata](https://docs.getlago.com/guide/customers/customer-metadata) & [credit notes](https://github.com/getlago/lago/wiki/Refunds,-Coupons-&-Credit-Notes:-why-they-are-different) in invoices and set [invoice grace periods](https://www.getlago.com/blog/grace-period-to-adjust-invoice-usage). These features can enhance invoicing operations and compliance.

Additionally, Lago offers support for multiple languages for invoices and emails, making it a versatile solution for businesses operating in various countries or aiming for global expansion ([see more here](https://docs.getlago.com/api-reference/resources/locales)).

Companies also have the option to integrate our billing engine with an existing invoicing provider like Quickbooks, Netsuite, Bill.com, or Stripe. Learn more [here](https://docs.getlago.com/integrations/introduction).

## 4. Does Lago provide a customer self-service portal?

Yes. Lago allows you to effortlessly integrate the customer portal into your application, providing your customers with seamless access to detailed usage information and invoice data.

## 5. Does Lago provide Analytics and Reporting?

Lago is your go-to solution for in-depth analytics of your billing data. This gives you access to accurate revenue computation with ease and other critical financial information.

Analytics dashboard are accessible through both user interface and dedicated API endpoints to obtain the insights that matter most to you, like your monthly recurring revenues (if you use Stripe, you probably know how [difficult it is to gather this info](https://www.getlago.com/blog/calculating-stripe-mrr-is-difficult))

Learn more about analytics [here](https://docs.getlago.com/guide/analytics/overview).

## 6. Does Lago support different time zones?

Yes. Lago allows you to set time zones at a customer level, ensuring that usage ingestion, expiry dates and billing will be triggered based on the time zone of your customer.
Read more about why time zones matter [here](https://www.getlago.com/blog/bill-your-customers-in-their-timezone-not-yours).

## 7. What integrations does Lago support?

All Lago’s plans offer native integrations with third party tools for payments (Stripe Payments, GoCardless, Adyen), accounting (NetSuite, QuickBooks), taxes (Anrok), CRM (Salesforce) and others.

You can learn more about integrations [here](https://getlago.com/docs/integrations/introduction).

## 8. Does Lago support taxation?

Lago features automatic European tax detection integration for your customers. Learn more about Lago EU Taxes integration [here](https://getlago.com/docs/integrations/taxes/lago-eu-taxes).

You can also integrate with Anrok, the global sales tax platform for software companies. Learn more about this integration [here](https://getlago.com/docs/integrations/introduction#taxes-integrations).

## 9. Does Lago process payments?

Lago does not process payments directly but enables you to integrate with any payment processors (Stripe Payments, GoCardless, Adyen, etc). Learn more about payment integrations [here](https://getlago.com/docs/integrations/introduction#payments-integrations).

Lago will process and calculate how much you should charge a user and when, and send this information to your chosen payment gateway, so that your user can proceed to the actual payment. We also allow you to monitor payment status and track refunds.


# Gross revenue



Gross revenue represents the total income generated by your organization in a single month, giving you a complete overview of your financial performance.
We ensure a comprehensive approach, encompassing all types of discounts, such as credit notes, coupons, and credits, to provide you with a precise picture of your gross revenue.
In essence, it's the amount you should expect to receive every month.

**Our gross revenue calculation considers the following factors:**

1.  All `finalized` invoices, whether related to subscriptions or usage;
2.  Pay in advance fees, whether they are invoiceable or not;
3.  Invoices related to prepaid credits from wallets;
4.  One-off invoices; and
5.  Deducting the credit note amounts `refunded` to customers.

<Tabs>
  <Tab title="Dashboard">
    To access the Gross Revenue analytics dashboard:

    1.  Navigate to the "Analytics" section; and
    2.  Access the "Gross Revenue" Dashboard.

    <Frame caption="Gross revenue dashboard">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/analytics/images/gross-revenue.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Get Gross Revenue 
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request GET "$LAGO_URL/api/v1/analytics/gross_revenue?external_customer_id=hooli_1234&currency=USD" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      ```
    </CodeGroup>
  </Tab>

  <Tab title="SQL Query">
    <Info>
      The generated amounts are in cents, making it compatible with different currencies.
    </Info>

    <CodeGroup>
      ```sql SQL Query used by Lago
          --- Start date of the query is the organization creation date
          WITH organization_creation_date AS (
              SELECT
                  DATE_TRUNC('month', o.created_at) AS start_month
              FROM organizations o
              WHERE o.id = '__YOUR_ORGANIZATION_ID__'
          ),

          --- Generate a number of date series in the future
          all_months AS (
              SELECT
                  generate_series(
                      (SELECT start_month FROM organization_creation_date),
                      DATE_TRUNC('month', CURRENT_DATE + INTERVAL '10 years'), 
                      interval '1 month'
                  ) AS month
          ),

          --- Get value for all issued invoices
          issued_invoices AS (
              SELECT
                  i.id,
                  i.issuing_date,
                  i.total_amount_cents::float AS amount_cents,
                  i.currency,
                  COALESCE(SUM(refund_amount_cents::float),0) AS total_refund_amount_cents
              FROM invoices i
              LEFT JOIN customers c ON i.customer_id = c.id
              LEFT JOIN credit_notes cn ON cn.invoice_id = i.id
              WHERE i.organization_id = '__YOUR_ORGANIZATION_ID__'
                  AND i.status = 1
                  ---AND c.external_id = 'hooli_1234' --- FILTER BY CUSTOMER
              GROUP BY i.id, i.issuing_date, i.total_amount_cents, i.currency
              ORDER BY i.issuing_date ASC
          ),

          --- Get value for all instant charges (paid in advance but not invoiceable)
          instant_charges AS (
              SELECT
                  f.id,
                  f.created_at AS issuing_date,
                  f.amount_cents AS amount_cents,
                  f.amount_currency AS currency,
                  0 AS total_refund_amount_cents
              FROM fees f
              LEFT JOIN subscriptions s ON f.subscription_id = s.id
              LEFT JOIN customers c ON c.id = s.customer_id
              WHERE c.organization_id = '__YOUR_ORGANIZATION_ID__'
                  AND f.invoice_id IS NULL
                  AND f.pay_in_advance IS TRUE
                  ---AND c.external_id = 'hooli_1234' --- FILTER BY CUSTOMER
          ),

          --- Combine data to get total of gross revenue
          combined_data AS (
              SELECT
                  DATE_TRUNC('month', issuing_date) AS month,
                  currency,
                  COALESCE(SUM(amount_cents), 0) AS amount_cents,
                  COALESCE(SUM(total_refund_amount_cents), 0) AS total_refund_amount_cents
              FROM (
                  SELECT * FROM issued_invoices
                  UNION ALL
                  SELECT * FROM instant_charges
              ) AS gross_revenue
              GROUP BY month, currency, total_refund_amount_cents
          )

          --- Get gross revenue month over month
          SELECT
              am.month,
              cd.currency,
              SUM(cd.amount_cents - cd.total_refund_amount_cents) AS amount_cents
          FROM all_months am
          LEFT JOIN combined_data cd ON am.month = cd.month
          WHERE am.month <= DATE_TRUNC('month', CURRENT_DATE)
              ---AND am.month >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL '11 months') --- LAST 12 MONTHS
              AND cd.amount_cents IS NOT NULL
              --- AND cd.currency = 'EUR'
          GROUP BY am.month, cd.currency
          ORDER BY am.month
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Invoice collection



<Info>
  **PREMIUM FEATURE** ✨

  This dashboard is only available to users with a premium license. Please
  **[contact us](mailto:hello@getlago.com)** to get access to Lago Cloud and Lago
  Self-Hosted Premium.
</Info>

Our dashboard empowers you with insights into the number of invoices and their respective values across all payment statuses.
This means you can easily track the count of invoices with failed, pending, or successful payment statuses and ease your collection.

By simply clicking on any of the rows, you can gain access to a detailed list of invoices categorized by their status.
This feature proves valuable when you need to initiate a new payment intent or take specific actions related to invoice management.

<Tabs>
  <Tab title="Dashboard">
    To access the Invoice collection analytics dashboard:

    1.  Navigate to the "Analytics" section; and
    2.  Access the "Outstanding invoices" Dashboard.

    <Frame caption="Oustanding invoices dashboard">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/analytics/images/outstanding-invoices.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Get Oustanding Invoices
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request GET "$LAGO_URL/api/v1/analytics/invoice_collection?currency=USD" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      ```
    </CodeGroup>
  </Tab>

  <Tab title="SQL Query">
    <Info>
      The generated amounts are in cents, making it compatible with different currencies.
    </Info>

    <CodeGroup>
      ```sql SQL Query used by Lago
          --- Get start date of the organization
          WITH organization_creation_date AS (
              SELECT
                  DATE_TRUNC('month', o.created_at) AS start_month
              FROM organizations o
              WHERE o.id = '__YOUR_ORGANIZATION_ID__'
          )

          --- Generate a series of months
          , all_months AS (
              SELECT
                  generate_series(
                      (SELECT start_month FROM organization_creation_date),
                      DATE_TRUNC('month', CURRENT_DATE + INTERVAL '10 years'),
                      interval '1 month'
                  ) AS month
          )

          --- Get invoice number and value per status
          ,invoices_per_status AS (
              SELECT
                  DATE_TRUNC('month', i.issuing_date) AS month,
                  i.currency,
                  CASE
                      WHEN i.payment_status = 0 THEN 'pending'
                      WHEN i.payment_status = 1 THEN 'paid'
                      WHEN i.payment_status = 2 THEN 'failed'
                  END AS payment_status,
                  COALESCE(COUNT(*), 0) AS number_invoices,
                  COALESCE(SUM(i.total_amount_cents::float), 0) AS amount_cents
              FROM invoices i
              WHERE i.organization_id = '__YOUR_ORGANIZATION_ID__'
                  AND i.status = 1 --- ONLY FINALIZED INVOICES
              GROUP BY payment_status, month, currency
          )

          --- Get invoice total and amount per status per month till the current month
          SELECT
              am.month,
              payment_status,
              currency,
              COALESCE(number_invoices, 0) AS number_invoices,
              COALESCE(amount_cents, 0) AS amount_cents
          FROM all_months am
          LEFT JOIN invoices_per_status ips ON ips.month = am.month AND ips.payment_status IS NOT NULL
          WHERE am.month <= DATE_TRUNC('month', CURRENT_DATE)
              AND payment_status IS NOT NULL
              ---AND currency = '' --- Filter by currency if needed
          ORDER BY am.month, payment_status, currency;
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Overdue invoices



The Overdue Invoices dashboard displays the total amount from your finalized invoices that are either pending or failed and have passed their due date. It does not include voided or disputed invoices. At a glance, you can see what your customers owe you, providing quick insight into the state of your revenue collection.

<Tabs>
  <Tab title="Dashboard">
    To access the Overdue invoices dashboard:

    1.  Navigate to the "Analytics" section; and
    2.  Access the "Overdue invoices" Dashboard.

    Our overdue balance calculation considers the following factors:

    *   Finalized invoices;
    *   With pending or failed as a payment status; and
    *   A due date that is past;

    It is not taking into account invoices that are disputed or voided.

    <Frame caption="Overdue invoices dashboard">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/analytics/images/overdue-invoices.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Get Overdue balance
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request GET "$LAGO_URL/api/v1/analytics/overdue_balance?currency=USD" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      ```
    </CodeGroup>
  </Tab>

  <Tab title="SQL Query">
    <Info>
      The generated amounts are in cents, making it compatible with different currencies.
    </Info>

    <CodeGroup>
      ```sql SQL Query used by Lago
      --- Start date of the query is the organization creation date
      WITH organization_creation_date AS (
      SELECT
          DATE_TRUNC('month', o.created_at) AS start_month
      FROM organizations o
      WHERE o.id = '__YOUR_ORGANIZATION_ID__'
      ),

      --- Generate a number of date series in the future
      all_months AS (
      SELECT
          generate_series(
              (SELECT start_month FROM organization_creation_date),
              DATE_TRUNC('month', CURRENT_DATE + INTERVAL '10 years'), 
              interval '1 month'
          ) AS month
      ),

      --- Get total of overdue invoices
      payment_overdue_invoices AS (
      SELECT
        DATE_TRUNC('month', payment_due_date) AS month,
        i.currency,
        COALESCE(SUM(total_amount_cents), 0) AS total_amount_cents,
        array_agg(DISTINCT i.id) AS ids
      FROM invoices i
      LEFT JOIN customers c ON i.customer_id = c.id
      WHERE i.organization_id = :organization_id
      AND i.payment_overdue IS TRUE
      ---AND c.external_id = 'hooli_1234' --- FILTER BY CUSTOMER
      GROUP BY month, i.currency, total_amount_cents
      ORDER BY month ASC
      )

      --- Get overdue balances month over month
      SELECT
      am.month,
      #{select_currency_sql},
      SUM(invs.total_amount_cents) AS amount_cents,
      jsonb_agg(DISTINCT invs.ids) AS lago_invoice_ids
      FROM all_months am
      LEFT JOIN payment_overdue_invoices invs ON am.month = invs.month
      WHERE am.month <= DATE_TRUNC('month', CURRENT_DATE)
      ---AND am.month >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL '11 months') --- LAST 12 MONTHS
      --- AND cd.currency = 'EUR'
      AND invs.total_amount_cents IS NOT NULL
      GROUP BY am.month, invs.currency
      ORDER BY am.month;
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Monthly Recurring Revenue (MRR)



<Info>
  **PREMIUM FEATURE** ✨

  This dashboard is only available to users with a premium license. Please
  **[contact us](mailto:hello@getlago.com)** to get access to Lago Cloud and Lago
  Self-Hosted Premium.
</Info>

Monthly Recurring Revenue (MRR) serves as a crucial indicator of your subscription-based revenue stream.
It encapsulates the total monthly revenue derived from subscriptions that is recurring. It's important to highlight that our MRR calculation
method takes into account all types of coupons and taxes. We take a holistic approach to provide you with an accurate representation
of your recurring revenue.

It's worth noting that Lago's MRR calculations solely pertain to `subscription` fees. Usage-based metrics,
whether recurring or metered, are not factored into the MRR calculations. This distinction ensures that your MRR figures
specifically reflect your subscription-based revenue, helping you gain a clear understanding of your core financial
performance.

**Here's our MRR calculation method:**

*   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 `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.

<Info>
  Please note that the UI's MRR total summary displays the MRR from the most recently **completed** billing month.
</Info>

<Tabs>
  <Tab title="Dashboard">
    To access the MRR analytics dashboard:

    1.  Navigate to the "Analytics" section; and
    2.  Access the "Monthly Recurring Revenue" Dashboard.

    <Frame caption="MRR dashboard">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/analytics/images/mrr.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Get MRR
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request GET "$LAGO_URL/api/v1/analytics/mrr?currency=USD" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      ```
    </CodeGroup>
  </Tab>

  <Tab title="SQL Query">
    <Info>
      The generated amounts are in cents, making it compatible with different currencies.
    </Info>

    <CodeGroup>
      ```sql SQL Query used by Lago
        --- Organization creation date is the start of this report
          WITH organization_creation_date AS (
              SELECT
                  DATE_TRUNC('month', o.created_at) AS month
              FROM organizations o
              WHERE o.id = '__YOUR_ORGANIZATION_ID__'
          ),

          --- Generate series of month
          all_months AS (
              SELECT
                  *
              FROM generate_series(
                  (SELECT min(month) FROM organization_creation_date),
                  date_trunc('month', now()) + interval '10 years',
                  interval '1 month'
              ) AS month
          ),

          --- Get invoice details for recurring subscriptions with finalized invoices and number of months billed
          invoice_details AS (
              SELECT
                  f.subscription_id,
                  f.invoice_id,
                  c.name,
                  ((f.amount_cents - f.precise_coupons_amount_cents) + f.taxes_amount_cents) AS amount_cents,
                  f.amount_currency AS currency,
                  i.issuing_date,
                  (EXTRACT(DAY FROM CAST(properties ->> 'to_datetime' AS timestamp) - CAST(properties ->> 'from_datetime' AS timestamp)) 
                  + EXTRACT(HOUR FROM CAST(properties ->> 'to_datetime' AS timestamp) - CAST(properties ->> 'from_datetime' AS timestamp)) / 24 
                  + EXTRACT(MINUTE FROM CAST(properties ->> 'to_datetime' AS timestamp) - CAST(properties ->> 'from_datetime' AS timestamp)) / 1440) / 30.44 AS billed_months,
                  p.pay_in_advance,
                  CASE
                      WHEN p.interval = 0 THEN 'weekly'
                      WHEN p.interval = 1 THEN 'monthly'
                      WHEN p.interval = 2 THEN 'yearly'
                      WHEN p.interval = 3 THEN 'quarterly'
                  END AS plan_interval
              FROM fees f
              LEFT JOIN invoices i ON f.invoice_id = i.id
              LEFT JOIN customers c ON c.id = i.customer_id
              LEFT JOIN organizations o ON o.id = c.organization_id
              LEFT JOIN subscriptions s ON f.subscription_id = s.id
              LEFT JOIN plans p ON p.id = s.plan_id
              WHERE fee_type = 2
                  AND c.organization_id = '__YOUR_ORGANIZATION_ID__'
                  AND i.status = 1
              ORDER BY issuing_date ASC
          )

          --- Distribute quarterly revenue prorated for the next months
          ,quarterly_advance AS (
              SELECT
                  DATE_TRUNC('month', issuing_date) + INTERVAL '1 month' * gs.month_index AS month,
                  CASE 
                      WHEN gs.month_index = 0 THEN (amount_cents / billed_months) * (DATE_PART('day', DATE_TRUNC('month', issuing_date + INTERVAL '1 month') - issuing_date) / DATE_PART('day', DATE_TRUNC('month', issuing_date + INTERVAL '1 month') - DATE_TRUNC('month', issuing_date)))
                      WHEN gs.month_index = CEIL(billed_months) - 1 THEN (amount_cents - (amount_cents / billed_months) * (FLOOR(billed_months) - 1 + (DATE_PART('day', DATE_TRUNC('month', issuing_date + INTERVAL '1 month') - issuing_date) / DATE_PART('day', DATE_TRUNC('month', issuing_date + INTERVAL '1 month') - DATE_TRUNC('month', issuing_date)))))
                      ELSE amount_cents / billed_months
                  END AS amount_cents,
                  currency,
                  name
              FROM invoice_details,
              LATERAL GENERATE_SERIES(0, CEIL(billed_months) - 1) AS gs(month_index)
              WHERE pay_in_advance = TRUE
                  AND plan_interval = 'quarterly'
          )

          --- Distribute quarterly revenue prorated for the past months
          ,quarterly_arrears AS (
              SELECT
                  DATE_TRUNC('month', issuing_date) - INTERVAL '1 month' * gs.month_index AS month,
                  CASE 
                      WHEN gs.month_index < CEIL(billed_months::numeric) - 1 THEN 
                          amount_cents::numeric / billed_months::numeric
                      ELSE 
                          amount_cents::numeric - (amount_cents::numeric / billed_months::numeric) * (CEIL(billed_months::numeric) - 1)
                  END AS amount_cents,
                  currency,
                  name
              FROM invoice_details,
              LATERAL GENERATE_SERIES(0, CEIL(billed_months::numeric) - 1) AS gs(month_index)
              WHERE pay_in_advance = FALSE
                  AND plan_interval = 'quarterly'
          )

          --- Distribute yearly revenue prorated for the next months
          ,yearly_advance AS (
              SELECT
                  DATE_TRUNC('month', issuing_date) + INTERVAL '1 month' * gs.month_index AS month,
                  CASE 
                      WHEN gs.month_index = 0 THEN (amount_cents / billed_months) * (DATE_PART('day', DATE_TRUNC('month', issuing_date + INTERVAL '1 month') - issuing_date) / DATE_PART('day', DATE_TRUNC('month', issuing_date + INTERVAL '1 month') - DATE_TRUNC('month', issuing_date)))
                      WHEN gs.month_index = CEIL(billed_months) - 1 THEN (amount_cents - (amount_cents / billed_months) * (FLOOR(billed_months) - 1 + (DATE_PART('day', DATE_TRUNC('month', issuing_date + INTERVAL '1 month') - issuing_date) / DATE_PART('day', DATE_TRUNC('month', issuing_date + INTERVAL '1 month') - DATE_TRUNC('month', issuing_date)))))
                      ELSE amount_cents / billed_months
                  END AS amount_cents,
                  currency,
                  name
              FROM invoice_details,
              LATERAL GENERATE_SERIES(0, CEIL(billed_months) - 1) AS gs(month_index)
              WHERE pay_in_advance = TRUE
                  AND plan_interval = 'yearly'
          )

          --- Distribute yearly revenue prorated for the past months
          ,yearly_arrears AS (
              SELECT
                  DATE_TRUNC('month', issuing_date) - INTERVAL '1 month' * gs.month_index AS month,
                  CASE 
                      WHEN gs.month_index < CEIL(billed_months::numeric) - 1 THEN 
                          amount_cents::numeric / billed_months::numeric
                      ELSE 
                          amount_cents::numeric - (amount_cents::numeric / billed_months::numeric) * (CEIL(billed_months::numeric) - 1)
                  END AS amount_cents,
                  currency,
                  name
              FROM invoice_details,
              LATERAL GENERATE_SERIES(0, CEIL(billed_months::numeric) - 1) AS gs(month_index)
              WHERE pay_in_advance = FALSE
                  AND plan_interval = 'yearly'
          )

          --- Distribute monthly revenue for the current month of issuing
          ,monthly AS (
              SELECT
                  DATE_TRUNC('month', issuing_date) - interval '1 month' * generate_series(0, 0, -1) AS month,
                  amount_cents,
                  currency
              FROM invoice_details
              WHERE plan_interval = 'monthly'
          )

          --- Distribute weekly revenue by dividing number of invoices in a month by 4.33 (average number of weeks in a month)
          ,weekly AS (
              SELECT
                  DATE_TRUNC('month', issuing_date) - interval '1 month' * generate_series(0, 0, -1) AS month,
                  currency,
                  (SUM(amount_cents) / COUNT(*)) * 4.33 AS amount_cents
              FROM invoice_details
              WHERE plan_interval = 'weekly'
              GROUP BY month, currency
          )

          ,consolidated_mrr AS (
              SELECT month, amount_cents::numeric, currency
              FROM quarterly_arrears
              UNION ALL
              SELECT month, amount_cents::numeric, currency
              FROM quarterly_advance
              UNION ALL
              SELECT month, amount_cents::numeric, currency
              FROM yearly_arrears
              UNION ALL
              SELECT month, amount_cents::numeric, currency
              FROM yearly_advance
              UNION ALL
              SELECT month, amount_cents::numeric, currency
              FROM monthly
              UNION ALL
              SELECT month, amount_cents::numeric, currency
              FROM weekly
          )

          SELECT
              am.month,
              cm.currency,
              COALESCE(SUM(cm.amount_cents),0) AS amount_cents
          FROM all_months am
          LEFT JOIN consolidated_mrr cm ON cm.month = am.month
          WHERE am.month <= DATE_TRUNC('month', CURRENT_DATE)
              AND am.month >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL '11 months') --- LAST 12 MONTHS
              ---AND cm.currency = ''
          GROUP BY am.month, cm.currency
          ORDER BY am.month ASC
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Overview



Lago is your go-to solution for in-depth billing analytics data, enabling you to accurately calculate revenue with ease.
Our commitment to delivering valuable insights drives us to regularly expand our suite of revenue dashboards.
These dashboards are not just a feature; they're the very first thing you encounter when you log in to your Lago account,
ensuring you have immediate access to critical financial information. Additionally, users can access this data via our API for seamless integration.

## Currency filter

Keep in mind that our revenue analytics dashboards are segmented by currency.
If you have invoices in multiple currencies, please note that no conversion rate is applied.

## Time filter

Within the user interface, you have the ability to filter metrics based on timeframes. Your options include:

*   `Yearly`: Covers the last 12 months
*   `Monthly`: Focuses on the current month
*   `Quarterly`: Encompasses the past 4 months

## API-Driven revenue insights

At Lago, our analytics dashboards are accessible through both the user interface and dedicated API endpoints.
When interacting with our APIs, you have the flexibility to fine-tune your data retrieval by incorporating currency-based
filters. This means you can seamlessly obtain the insights that matter most to you, all while harnessing the power of
Lago's analytics capabilities.

## Data caching strategy

Lago optimizes data retrieval for revenue analytics in both UI and API endpoints through strategic caching.
This ensures faster performance. However, it's important to note that **this data is refreshed every 4 hours**.
Consequently, there may be a slight delay in reflecting the most current revenue data at the time of access.

## Data models

If you're looking to craft custom queries from our self-hosted database, here are key insights to empower your interaction with our data models:

**Invoice Types**:

*   `subscription`: 0
*   `add_on`: 1
*   `credit`: 2
*   `one_off`: 3

**Payment Status**:

*   `pending`: 0
*   `succeeded`: 1
*   `failed`: 2

**Invoice Status**

*   `draft`: 0
*   `finalized`: 1
*   `voided`: 2


# Aggregation examples



Imagine you are a Tracking API company (such as
[Segment.com](https://www.segment.com/)). For the same events received, the
result provided by the aggregation types proposed by Lago is completely
different. This result is used to charge your customers.

## Example of events received[](#example-of-events-received "Direct link to heading")

You decided to charge the `Tracked Pages`. **This is your Billable metric.**
Here are the 2 events sent by your backend to Lago, based on the consumption of
a customer:

```json Event received n°1
{
  "transaction_id": "1111-1111-1111-1111",
  "external_customer_id": "1",
  "timestamp": "2022-03-16T00:00:00Z",
  "code": "tracked_pages",
  "properties": {
    "tracked_user_id": "1234-5678-9098-7654",
    "pageviews": 10
  }
}
```

```json Event received n°2
{
  "transaction_id": "2222-2222-2222-2222",
  "external_customer_id": "1",
  "timestamp": "2022-03-17T00:00:00Z",
  "code": "tracked_pages",
  "properties": {
    "tracked_user_id": "1234-5678-9098-7654",
    "pageviews": 20
  }
}
```

Let's see below the differences between the aggregation types.

## Differences between the aggregation types[](#differences-between-the-aggregation-types "Direct link to heading")

| Aggregation      | Code                                                     | Units to be charged |
| ---------------- | -------------------------------------------------------- | ------------------- |
| **COUNT**        | `COUNT(tracked_pages)`                                   | 2                   |
| **SUM**          | `SUM(tracked_pages.properties.pageviews)`                | 30                  |
| **MAX**          | `MAX(tracked_pages.properties.pageviews)`                | 20                  |
| **COUNT UNIQUE** | `UNIQUE_COUNT(tracked_pages.properties.tracked_user_id)` | 1                   |

Based on the aggregation type you defined for your Billable metric
`Tracked Pages`, the result that is going to be charged to your customer is
completely different. Make sure to choose the right aggregation type for all
your Billable metrics. If you need help, don't hesitate to reach out the Lago
Team!


# COUNT



The count aggregation type is straightforward. It tallies the exact number of events received during a period.

<Frame caption="COUNT calculation method">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/count.png" />
</Frame>

## COUNT billable metric

<Tabs>
  <Tab title="Dashboard">
    Here is how you can create a count aggregation from the UI:

    1.  Access the **"Billable metrics"** section via the side menu;
    2.  Create a new billable metric;
    3.  Define a name, a code and an optional description;
    4.  Select **"count"** as the aggregation type;
    5.  Apply dimension groups if any; and
    6.  Click **"Add billable metric"**.

    <Info>
      This billable metric is `metered` only, meaning it cannot be recurring, and the number
      of billing units resets to 0 at the end of each period.
    </Info>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash
          LAGO_URL="https://api.getlago.com"
          API_KEY="__YOUR_API_KEY__"

          curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
          --header "Authorization: Bearer $API_KEY" \
          --header 'Content-Type: application/json' \
          --data-raw '{
              "billable_metric": {
              "name": "API Request",
              "code": "api_requests",
              "description": "Number of API requests.",
              "aggregation_type": "count_agg",
              "group": {}
          }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Calculation example

Lago calculates the `COUNT(events.code)` for the two following events received.

```json
//Event received #1
{
    "transaction_id": "transaction_1",
    "external_customer_id": "1",
    "timestamp": "2022-03-16T00:00:00Z",
    "code": "api_requests",
    "properties": {}
}

//Event received #2
{
    "transaction_id": "transaction_2",
    "external_customer_id": "1",
    "timestamp": "2022-03-17T00:00:00Z",
    "code": "api_requests",
    "properties": {}
}
```

In that case, with this aggregation type, Lago simply counts the number events received, **resulting in a billable value of 2 units.**


# UNIQUE COUNT



The unique count aggregation type counts only the unique values of a specified event property.

<Frame caption="UNIQUE COUNT calculation method">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/count-unique.png" />
</Frame>

## UNIQUE COUNT billable metric

<Tabs>
  <Tab title="Dashboard">
    Here is how you can create a unique count aggregation from the UI:

    1.  Access the **"Billable metrics"** section via the side menu;
    2.  Create a new billable metric;
    3.  Define a name, a code and an optional description;
    4.  Select **"count unique"** as the aggregation type;
    5.  Define it this metric is `metered` or `recurring`;
    6.  Define the property to aggregate;
    7.  Apply dimension groups if any; and
    8.  Click **"Add billable metric"**.

    <Info>
      This billable metric can be both `metered` or `recurring`.
    </Info>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash
          LAGO_URL="https://api.getlago.com"
          API_KEY="__YOUR_API_KEY__"

          curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
          --header "Authorization: Bearer $API_KEY" \
          --header 'Content-Type: application/json' \
          --data-raw '{
              "billable_metric": {
              "name": "API Request",
              "code": "api_requests",
              "description": "Number of API requests.",
              "aggregation_type": "unique_count_agg",
              "field_name": "request_id",
              "group": {}
          }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Calculation example

Lago calculates the `COUNT_DISTINCT(events.properties.property_name)` for the two following events received.

```json
//Event received #1
{
    "transaction_id": "transaction_1",
    "external_customer_id": "1",
    "timestamp": "2022-03-16T00:00:00Z",
    "code": "api_requests",
    "properties": {
        "request_id": "id_1"
    }
}

//Event received #2
{
    "transaction_id": "transaction_2",
    "external_customer_id": "1",
    "timestamp": "2022-03-17T00:00:00Z",
    "code": "api_requests",
    "properties": {
        "request_id": "id_1"
    }
}
```

In that case, with this aggregation type, Lago only counts the unique values `request_id` property in the event payloads, **resulting in a billable value of 1 unit.**


# CUSTOM



<Info>
  **Premium feature ✨**:

  This feature is only available to users with a premium license. Please **[contact us](mailto:hello@getlago.com)** to get access this feature.
</Info>

Lago's basic interface and API allow you to configure metrics using conditional statements and predefined functions for usage aggregation.
However, for more sophisticated metrics, you may require more complex aggregation capabilities than those provided by Lago's default settings.
To address this need, Lago can parse your custom code, enabling you to implement advanced billing rules and custom aggregation logic.

By using custom code for aggregation, you gain complete flexibility over your usage metrics, allowing you to define and tailor them to your specific requirements.
This feature empowers you to create bespoke solutions that precisely match your billing needs.
If you're interested in leveraging custom code aggregation, please contact our team to enable this feature.


# LATEST



The latest aggregation type selects the most recent value of a specified event property from all received events.

<Frame caption="LATEST calculation method">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/latest.png" />
</Frame>

## LATEST billable metric

<Tabs>
  <Tab title="Dashboard">
    Here is how you can create a max aggregation from the UI:

    1.  Access the **"Billable metrics"** section via the side menu;
    2.  Create a new billable metric;
    3.  Define a name, a code and an optional description;
    4.  Select **"latest"** as the aggregation type;
    5.  Define the property to aggregate;
    6.  Apply dimension groups if any; and
    7.  Click **"Add billable metric"**.

    <Info>
      This billable metric is `metered` only, meaning it cannot be recurring, and the number of billing units resets to 0 at the end of each period.
    </Info>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash
          LAGO_URL="https://api.getlago.com"
          API_KEY="__YOUR_API_KEY__"

          curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
          --header "Authorization: Bearer $API_KEY" \
          --header 'Content-Type: application/json' \
          --data-raw '{
              "billable_metric": {
              "name": "API Request",
              "code": "api_requests",
              "description": "Number of API requests.",
              "aggregation_type": "latest_agg",
              "field_name": "total_requests",
              "group": {}
          }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Calculation example

Lago calculates the `LAST_VALUE(events.properties.property_name) OVER ([PARTITION BY events.timestamp])` for the two following events received.

```json
//Event received #1
{
    "transaction_id": "transaction_1",
    "external_customer_id": "1",
    "timestamp": "2022-03-16T00:00:00Z",
    "code": "api_requests",
    "properties": {
        "total_requests": 20
    }
}

//Event received #2
{
    "transaction_id": "transaction_2",
    "external_customer_id": "1",
    "timestamp": "2022-03-17T00:00:00Z",
    "code": "api_requests",
    "properties": {
        "total_requests": 10
    }
}
```

In that case, with this aggregation type, Lago takes the latest value of `total_requests` property from all events, **resulting in a billable value of 10 units.**


# MAX



The max aggregation type selects the highest value of a specified event property from all received events.

<Frame caption="MAX calculation method">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/max.png" />
</Frame>

## MAX billable metric

<Tabs>
  <Tab title="Dashboard">
    Here is how you can create a max aggregation from the UI:

    1.  Access the **"Billable metrics"** section via the side menu;
    2.  Create a new billable metric;
    3.  Define a name, a code and an optional description;
    4.  Select **"max"** as the aggregation type;
    5.  Define the property to aggregate;
    6.  Apply dimension groups if any; and
    7.  Click **"Add billable metric"**.

    <Info>
      This billable metric is `metered` only, meaning it cannot be recurring, and the number of billing units resets to 0 at the end of each period.
    </Info>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash
          LAGO_URL="https://api.getlago.com"
          API_KEY="__YOUR_API_KEY__"

          curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
          --header "Authorization: Bearer $API_KEY" \
          --header 'Content-Type: application/json' \
          --data-raw '{
              "billable_metric": {
              "name": "API Request",
              "code": "api_requests",
              "description": "Number of API requests.",
              "aggregation_type": "max_agg",
              "field_name": "total_requests",
              "group": {}
          }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Calculation example

Lago calculates the `MAX(events.properties.property_name)` for the two following events received.

```json
//Event received #1
{
    "transaction_id": "transaction_1",
    "external_customer_id": "1",
    "timestamp": "2022-03-16T00:00:00Z",
    "code": "api_requests",
    "properties": {
        "total_requests": 20
    }
}

//Event received #2
{
    "transaction_id": "transaction_2",
    "external_customer_id": "1",
    "timestamp": "2022-03-17T00:00:00Z",
    "code": "api_requests",
    "properties": {
        "total_requests": 10
    }
}
```

In that case, with this aggregation type, Lago takes the higest value of `total_requests` property from all events, **resulting in a billable value of 20 units.**


# Overview

Aggregation types will define how consumption will be measured.

Here is the full list of **aggregation types** officially
supported by Lago.

| Aggregation      | Description                                                                        | Transcription                                                                                                                                                |
| ---------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **COUNT**        | Count the number of times an incoming event occurs                                 | `COUNT(events.code)`                                                                                                                                         |
| **COUNT UNIQUE** | Count the number of unique value of a defined property for incoming events         | `COUNT_DISTINCT(events.properties.property_name)`                                                                                                            |
| **LATEST**       | Get the latest value of a defined property for incoming events                     | `LAST_VALUE(events.properties.property_name) OVER ([PARTITION BY events.timestamp])`                                                                         |
| **MAX**          | Get the maximum value of a defined property for incoming events                    | `MAX(events.properties.property_name)`                                                                                                                       |
| **SUM**          | Sum a defined property for incoming events                                         | `SUM(events.properties.property_name)`                                                                                                                       |
| **WEIGHTED SUM** | Sum a defined property for incoming events, prorated based on time used per period | `SUM(events.properties.property_name) / (DATEDIFF(SECOND, timestamp.event_1, timestamp.event_2) + 1) * (DATEDIFF(SECOND, 'period_start', 'period_end') + 1)` |
| **CUSTOM**       | Define a custom code for your aggregation                                          | Custom code                                                                                                                                                  |

<Note>Except the `COUNT` (that is counting the number of times an event occurs), the
other types aggregate over a single property of the event. **The result of this
aggregation will be used to charge your customers.**</Note>


# SUM



The sum aggregation type adds up the value of a defined event property.

<Frame caption="SUM calculation method">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/sum.png" />
</Frame>

## SUM billable metric

<Tabs>
  <Tab title="Dashboard">
    Here is how you can create a sum aggregation from the UI:

    1.  Access the **"Billable metrics"** section via the side menu;
    2.  Create a new billable metric;
    3.  Define a name, a code and an optional description;
    4.  Select **"sum"** as the aggregation type;
    5.  Define it this metric is `metered` or `recurring`;
    6.  Define the property to aggregate;
    7.  Apply dimension groups if any; and
    8.  Click **"Add billable metric"**.

    <Info>
      This billable metric can be both `metered` or `recurring`.
    </Info>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash
          LAGO_URL="https://api.getlago.com"
          API_KEY="__YOUR_API_KEY__"

          curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
          --header "Authorization: Bearer $API_KEY" \
          --header 'Content-Type: application/json' \
          --data-raw '{
              "billable_metric": {
              "name": "API Request",
              "code": "api_requests",
              "description": "Number of API requests.",
              "aggregation_type": "sum_agg",
              "field_name": "total_requests",
              "group": {}
          }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Calculation example

Lago calculates the `SUM(events.properties.property_name)` for the two following events received.

```json
//Event received #1
{
    "transaction_id": "transaction_1",
    "external_customer_id": "1",
    "timestamp": "2022-03-16T00:00:00Z",
    "code": "api_requests",
    "properties": {
        "total_requests": 20
    }
}

//Event received #2
{
    "transaction_id": "transaction_2",
    "external_customer_id": "1",
    "timestamp": "2022-03-17T00:00:00Z",
    "code": "api_requests",
    "properties": {
        "total_requests": 10
    }
}
```

In that case, with this aggregation type, Lago adds up the values of the `total_requests` property in the event payloads, **resulting in a billable value of 30 units.**


# WEIGHTED SUM



The Weighted Sum aggregation type adds up the value of a defined event property and prorates it based on time used per period.
This is especially handy for automated GB/second calculations, for instance.

<Info>
  Currently, prorating is available **per second per period**.
  Feel free to reach out if you need additional proration options, such as hourly rates.
</Info>

<Frame caption="WEIGHTED SUM calculation method">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/weighted-sum.png" />
</Frame>

## WEIGHTED SUM billable metric

<Tabs>
  <Tab title="Dashboard">
    Here is how you can create a weighted sum aggregation from the UI:

    1.  Access the **"Billable metrics"** section via the side menu;
    2.  Create a new billable metric;
    3.  Define a name, a code and an optional description;
    4.  Select **"weighted sum"** as the aggregation type;
    5.  Define it this metric is `metered` or `recurring`;
    6.  Define the property to aggregate;
    7.  Define the `weighted_interval` used for time proration. Currently, Lago only supports `seconds`.
    8.  Apply dimension groups if any; and
    9.  Click **"Add billable metric"**.

    <Info>
      This billable metric can be both `metered` or `recurring`.
    </Info>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash
          LAGO_URL="https://api.getlago.com"
          API_KEY="__YOUR_API_KEY__"

          curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
          --header "Authorization: Bearer $API_KEY" \
          --header 'Content-Type: application/json' \
          --data-raw '{
              "billable_metric": {
              "name": "GB Seconds",
              "code": "gb/s",
              "description": "Gigabytes prorated per seconds used per period",
              "aggregation_type": "weighted_sum_agg",
              "weighted_interval": "seconds",
              "field_name": "gb",
              "group": {}
          }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Calculation example

Lago calculates the `SUM(events.properties.property_name) / (DATEDIFF(SECOND, timestamp.event_1, timestamp.event_2) + 1) * (DATEDIFF(SECOND, 'period_start', 'period_end') + 1)` for the two following events received.

```json
//Event received #1
{
    "transaction_id": "transaction_1",
    "external_customer_id": "1",
    "timestamp": "2022-03-16T00:00:00Z",
    "code": "gb/s",
    "properties": {
        "gb": 20
    }
}

//Event received #2
{
    "transaction_id": "transaction_2",
    "external_customer_id": "1",
    "timestamp": "2022-03-17T00:00:00Z",
    "code": "gb/s",
    "properties": {
        "gb": 10
    }
}
```

In that case, with this aggregation type, Lago adds up the values of the `gb` property in the event payloads, but prorates it based on time used during the current period.
Keep in mind that the entire month comprises 2,678,400 seconds. The first 20 GB has been used for a day (86,400 seconds), and the 30 GB (20 + 10) has been used for 15 days (1,296,000 seconds till the end of the month):

*   (20 / 2678400) x 86400 = 0.64516129032 GB/s
*   (30 / 2678400) x 1296000 = 14.5161290323 GB/s
*   0.64516129032 + 14.5161290323 = **15.1612903226 GB/s**


# Create billable metrics

Billable metrics define how incoming events are aggregated in order to measure consumption.

If you want to charge your customers for the use of a particular feature, then
you should create the corresponding billable metric.

<Tabs>
  <Tab title="Dashboard">
    To add a new billable metric through the user interface:

    *   Enter its `name`;
    *   Assign it a `code` which will be used as the name of the event sent from your
        backend;
    *   Add a `description` *(optional)*;
    *   Select the `aggregation type` which will define how consumption will be
        measured;
    *   Define the aggregation property `field_name` to aggregate on;
    *   Define `groups` if you price several dimensions for a same billing component; and
    *   Define if this billable metric is `recurring` and kept in memory period over period, or resume to 0 at the end of each period.
  </Tab>

  <Tab title="API">
    Here are few examples of billable metrics you can create:

    <CodeGroup>
      ```bash Storage
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "billable_metric": {
            "name": "Storage",
            "code": "storage",
            "description": "Number of GB used",
            "aggregation_type": "sum_agg",
            "field_name": "gb",
            "recurring": false,
            "group": {
              "key": "provider",
              "value": ["aws", "google", "azure"]
            }
          }
        }'
      ```

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

      curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "billable_metric": {
            "name": "Seats",
            "code": "seats",
            "description": "Active seats added",
            "aggregation_type": "unique_count_agg",
            "field_name": "seat_id",
            "recurring": true
          }
        }'
      ```

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

      curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "billable_metric": {
            "name": "CPU",
            "code": "cpu",
            "description": "Maximum number of CPUs used",
            "aggregation_type": "max_agg",
            "field_name": "total_cpu",
            "recurring": false
          }
        }'
      ```

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

      curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "billable_metric": {
            "name": "Payments",
            "code": "payments",
            "description": "Card payments issued",
            "aggregation_type": "sum_agg",
            "field_name": "amount",
            "recurring": false
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

The next section describes the different
[aggregation types](/guide/billable-metrics/aggregation-types). In addition to this, we have added some
[examples](/guide/billable-metrics/aggregation-types/aggregation-examples) to help you understand the relationship
between incoming events and billable metrics.


# Delete billable metrics



You may delete a billable metric linked to [charges](/guide/plans/charges) associated
with existing [subscriptions](/guide/subscriptions/assign-plan).

If you do so:

*   The events associated with this billable metric, which are assigned to the
    current billing period or linked to `draft` invoices, will be immediately
    deleted;
*   The charges associated with this billable metric will be immediately removed
    from all plans and existing subscriptions;
*   The charges associated with this billable metric will no longer be included in
    the [current usage](/api-reference/customer-usage/customer-usage-object) of the customers
    concerned; and
*   The charges associated with this billable metric will be immediately removed
    from all `draft` invoices linked to these subscriptions.

However, the charges associated with this billable metric will still be included
in all `finalized` invoices linked to these subscriptions.

<Info>
  After deleting a billable metric, you can create a new one using the same
  code. However, past events will not be linked to this new billable metric.
</Info>

<Tabs>
  <Tab title="Dashboard">
    ![How to delete a billable metric](https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/billable-metrics-delete-68cd9763df888a65237c8f0f5c85358a.png)
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Delete "Storage" metric
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request DELETE "$LAGO_URL/api/v1/billable_metrics/storage" \
        --header "Authorization: Bearer $API_KEY"
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Filters

When setting up your pricing, you may want to filters events according to their property. To do so, you can create filters for your billable metric.

## Create filters[](#create-filters "Direct link to heading")

Your company provides DevOps services and you want to charge your customers for compute capacity by the hour.

In your Lago account, you create a `compute` billable metric that calculates the total number of hours (i.e. `SUM(properties.hours)`).

As your customers can choose from different cloud providers and define a region, you need to filter usage records (i.e. events) according to the provider and region.

On the configuration page of your billable metric, you can define two filters: `provider` and `region`, with all the necessary values (see snippet below).

<Tabs>
  <Tab title="Dashboard">
    1.  Create a new billable metric;
    2.  Add a new filter; and
    3.  Define your different filters.

    <Frame caption="How to add filters">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/billable-metrics/images/add-filters.gif" />
    </Frame>
  </Tab>

  <Tab title="API">
    Here are few examples of billable metrics you can create:

    <CodeGroup>
      ```bash Billable metrics with filters {14-23}
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "billable_metric": {
            "name": "Compute",
            "code": "compute",
            "aggregation_type": "sum_agg",
            "field_name": "hours",
            "recurring": false,
            "filters": [
              {
                "key": "provider",
                "values": ["aws", "google", "azure"]
              },
              {
                "key": "region",
                "values": ["europe", "africa", "asia", "north_america"]
              }
            ]
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

Below is an example of an event including two group values for the billable metric described above:

```json Event including a group value
LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/events" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
    "event": {
      "transaction_id": "event_001",
      "external_customer_id": "customer_1234",
      "code": "compute",
      "timestamp": 1668461043,
      "properties": {
        "hours": 0.07,
        "provider": "aws",
        "region": "europe"
      }
    }
  }'
```

<Warning>
  Values are case-sensitive. If you don't use the exact value when pushing
  events, they will not be taken into account. Following our example: the
  expected value is `"aws"` and `"AWS"` is an invalid value.
</Warning>

You can also create billable metrics with dimensions
[via the API](/api-reference/billable-metrics/create).

## Edit filters

You can edit billable metric filters associated with existing subscriptions. It’s important to note that making changes to these metric filters can have an impact on all plans where this billable metric is defined as a charge. Here’s an example to illustrate the impact of editing a billable metric:

```json
From Payload A:
{
  "billable_metric": {
    "name": "gigabyte",
    "code": "gigabyte",
    "aggregation_type": "sum_agg",
    "field_name": "total",
    "filters": [
	    {
	      "key": "region",
	      "values": [
	        "usa",
	        "europe",
	      ]
	    }
    ]
  }
}

To Payload B:
{
  "billable_metric": {
    "name": "gigabyte",
    "code": "gigabyte",
    "aggregation_type": "sum_agg",
    "field_name": "total",
    "filters": [
	    {
	      "key": "region",
	      "values": [
	        "USA",
	        "europe",
	        "africa"
	      ]
	    }
    ]
  }
}
```

Note that each filter's keys and values are case-sensitive. Here's how Lago handles these changes:

1.  Since `"region": "europe"` remains the same between both payloads, this filter remains in the billable metric.
2.  As `"region": "usa"` is present in Payload A but not in Payload B, this filter is removed from the billable metric.
3.  As `"region": "USA"` is not present in Payload A but is present in Payload B, this filter will be created in the billable metric.
4.  Similarly, as `"region": "africa"` is not present in Payload A but is present in Payload B, this filter will be created in the billable metric.

When this billable metric is associated with charges, editing it will impact all plans where it is defined.

*   If an existing filter combination remains the same (case 1), Lago will retain this specific filter from the filters combination in all associated charges.
*   If an existing filter combination is removed from the billable metric (case 2), Lago will remove this specific filter from the filters combination in all associated charges.
*   If a new filter combination is created in the billable metric (case 3 and 4), Lago will not automatically add this filter in the filters combination in all associated charges; you will need to add them manually.


# Recurring vs metered



## Recurring billable metrics[](#recurring "Direct link to heading")

<Tabs>
  <Tab title="Dashboard">
    When you set `recurring: true` or choose the "recurring" option in the user interface, the billing aggregation for your billable metric
    will persist across billing periods. This means that the accumulated result will carry over and be used to charge the customer in
    subsequent periods.
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Seats example {14}
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "billable_metric": {
            "name": "Seats",
            "code": "seats",
            "description": "Active seats added",
            "aggregation_type": "unique_count_agg",
            "field_name": "seat_id",
            "recurring": true
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Metered billable metrics[](#metered "Direct link to heading")

<Tabs>
  <Tab title="Dashboard">
    Conversely, if you set `recurring: false` or select the "metered" option in the user interface, the billing aggregation for your billable
    metric will reset to zero at the end of each billing period. This ensures that the customer's charges reflect only the usage within
    that specific period.
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Storage example {14}
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "billable_metric": {
            "name": "Storage",
            "code": "storage",
            "description": "Number of GB used",
            "aggregation_type": "sum_agg",
            "field_name": "gb",
            "recurring": false
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Rounding

Lago aggregates your events in real time. You can add rounding rules to the final result.

## Rounding options

When creating or editing a billable metric, you have the option to apply rounding to the final aggregated value. By default, no rounding is applied. If you choose to enable rounding, you can select from the following options:

*   **Ceil**: Rounds up to the nearest integer;
*   **Floor**: Rounds down to the nearest integer; or
*   **Round**: Rounds to the nearest integer based on standard rounding rules.

## Precision types

### No precision

Omitting precision rounds to the nearest whole number (integer). By default, no specific precision is set for your rounding option.

👉 *Example: 123.4567 rounded with no precision → `123`.*

### Positive precision

Adding a positive precision rounds to a specific number of decimal places.

👉 *Example: 123.4567 rounded with precision 2 → `123.46` (two decimal places retained).*

### Negative precision

Adding a negative precision rounds to a specific position to the left of the decimal.

👉 *Example: 123.4567 rounded with precision -1 → `120` (rounds to the nearest ten).*


# SQL Expressions

For more advanced calculations, you can use SQL custom expressions. These expressions are helpful when the aggregation results for a billable metric require complex calculations.

## Creating a SQL Custom Expression

When creating a billable metric, you can choose between using a simple aggregation field or a custom expression.
**Custom expressions allow you to define more advanced computation logic**, which is useful when the required aggregation involves complex calculations that Lago should handle.

<Tabs>
  <Tab title="Dashboard">
    To add a custom expression through the user interface:

    *   Define the `name` and `code` for the billable metric;
    *   Choose an aggregation type;
    *   Select `Custom expressions` as the aggregation option instead of `Unique field`;
    *   Enter your custom expression in the expanded side panel;
    *   Test the custom expression; and
    *   Save the billable metric.

    <Frame caption="Create a custom expression for a billable metric">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/billable-metrics/images/custom-expression-creation.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    Here are few examples of custom expressions you can create for a billable metric:

    <CodeGroup>
      ```bash Storage {13}
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"

        curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
          --header "Authorization: Bearer $API_KEY" \
          --header 'Content-Type: application/json' \
          --data-raw '{
            "billable_metric": {
              "name": "Storage",
              "code": "storage",
              "description": "Number of GB consumed",
              "aggregation_type": "sum_agg",
              "expression": "(event.properties.ended_at - event.timestamp) / 3600",
              "field_name": "total",
              "recurring": false
            }
          }'
      ```

      ```bash Seats {13}
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"

        curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
          --header "Authorization: Bearer $API_KEY" \
          --header 'Content-Type: application/json' \
          --data-raw '{
            "billable_metric": {
              "name": "Seats",
              "code": "seats",
              "description": "Number of seats used",
              "aggregation_type": "unique_count_agg",
              "expression": "concat(event.properties.user_id, ‘-‘ , event.properties.app_id)",
              "field_name": "total",
              "recurring": true
            }
          }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<Info>
  Custom expressions can be used with any aggregation type except `COUNT`.
</Info>

## Examples of SQL Custom Expressions

A variety of SQL custom expressions are available for use. Here are a few examples:

*   **Concatenation:** `CONCAT(value1, '_', value2)`
*   **Math operations:** `((value1 * value2) / value3)`
*   **Rounding:** `ROUND(value1 / value2)`

If you need a SQL custom expression that isn't supported by default in Lago, **feel free to contact our team** or **consider contributing to the open-source version**.

## Testing your SQL Custom Expression

Lago provides a testing tool to help you validate the custom expressions you've created. A sample event is used to test your expression. You can override any field in the test event.
If your custom expression is incorrect, Lago will return an error, and you won't be able to save it until it's valid.

Keep the following in mind:

*   You can dynamically reference any event field within your expression; and
*   Use precise paths to reference fields accurately. For instance, to use the event timestamp, the path is `event.timestamp`. To reference a custom property sent with the event, the path is `event.properties.your_field`.

<Frame caption="Test your custom expression">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/billable-metrics/images/test-custom-expression.png" />
</Frame>


# Coupons

Coupons allow you to offer discounts to your customers. When you apply a coupon to a customer,  its value will be deducted from their next subscription invoice(s).

<Info>
  The value of the coupon is deducted from the amount of the invoice before tax.
</Info>

## Create a coupon[](#create-coupon "Direct link to heading")

<Tabs>
  <Tab title="Dashboard">
    To create a coupon through the user interface:

    1.  Access the **"Coupons"** section via the side menu;
    2.  Click **"Add a coupon"**;
    3.  Choose a name and a code for your coupon;
    4.  Select the type of coupon (i.e. fixed amount or percentage);
    5.  Define its value and frequency (i.e. will be applied once, over several
        periods or forever);
    6.  Choose if the coupon can be applied several times to the same customer
        account or not;
    7.  Choose whether or not to set an expiration date (i.e. date after which the
        coupon can no longer be redeemed);
    8.  Select the **plan(s)** or **billable metric(s)** to which the coupon applies (applies to all plans and metrics by default); and
    9.  Click **"Add coupon"** to confirm.

    <Info>
      The expiration date displayed in the app is based on the organization's timezone.
    </Info>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Create a coupon
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/coupons" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "coupon": {
            "name": "Startup Deal",
            "code": "startup_deal",
            "amount_cents": 5000,
            "amount_currency": "USD",
            "coupon_type": "fixed_amount",
            "reusable": true,
            "frequency": "recurring",
            "frequency_duration": 6,
            "expiration": "time_limit",
            "expiration_at": "2022-08-08T23:59:59Z",
            "applies_to": {
              "plan_codes": ["premium"],
              "billable_metric_codes": []
            }
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Apply coupons[](#apply-coupons "Direct link to heading")

<Warning>
  If the currency of the customer is already defined, the currency of the coupon
  must be the same, otherwise you will not be able to apply the coupon to the
  customer.
</Warning>

<Tabs>
  <Tab title="Dashboard">
    To apply a coupon to a customer:

    1.  Select a customer from the list;
    2.  Click **"Actions"** in the upper-right corner and select **"Apply coupon"**;
    3.  Select a coupon;
    4.  Override values and currency; and
    5.  Click **"Apply coupon"** to confirm.
  </Tab>

  <Tab title="API">
    You can also apply coupons via the API ([learn more](/api-reference/coupons/apply)).

    <CodeGroup>
      ```bash Apply a coupon to a customer
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/applied_coupons" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "applied_coupon": {
            "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
            "coupon_code": "startup_deal",
            "amount_cents": 6000,
            "amount_currency": "EUR",
            "frequency": "recurring",
            "frequency_duration": 3
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Application scope[](#application-scope "Direct link to heading")

<Info>
  You can apply several coupons to a customer. However, if a coupon has been
  marked as non-reusable, you will only be able to apply it once to the customer
  account, even if it has not been fully consumed. A coupon applied to a customer continues to apply beyond the expiration date.
</Info>

Coupons are deducted from future subscription invoices. As mentioned previously, the value of
the coupon is deducted from the amount of the invoice before tax.

For coupons whose value is a fixed amount:

*   **When the coupon only applies once** and its value is higher than the invoice
    amount, the remaining unused amount will be applied to the following invoices,
    until the coupon is totally consumed or removed; and
*   **When the coupon is recurring** and its value is higher than the invoice amount,
    any remaining unused amount will be lost, even if it is the last application
    period.

When several coupons are applied to the customer account, they will be deducted according to the following rules:

*   **Coupons limited to specific billable metrics will be deducted first** (if any, and if there is at least one subscription
    associated with the relevant metric);
*   **Coupons limited to specific plans will be deducted next** (if any, and if there is at least one subscription associated with the relevant plan); and
*   **Coupons that apply to all plans** will be deducted according to the date on which they were applied (i.e. the coupon that was applied first will be deducted first).

You can see the remaining value / number of remaining periods for each coupon in
the **"Overview"** tab of the customer view.

![Customer account with several coupons](https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/coupons-remaining.png)

<Info>Coupons do not apply to add-ons or any other one-off charges.</Info>

## Edit, terminate and delete coupons[](#edit-terminate-and-delete-coupons "Direct link to heading")

In the coupon view, you can click the **ellipsis icon** to see all available
actions:

1.  **Edit**: allows you to modify the name, code and settings of the coupon;
2.  **Terminate**: allows you to deactivate the coupon so that it cannot be
    applied to any new customer (customers to whom the coupon has already been
    applied continue to benefit from it); and
3.  **Delete**: allows you to delete the coupon and remove it from the list (this
    action cannot be undone).

<Info>
  You cannot modify the code, value and frequency of a coupon, or delete it, if
  it has already been applied to a customer.
</Info>

## Remove coupons[](#remove-coupons "Direct link to heading")

To remove a coupon that has been applied to a customer and is still active:

1.  Select the customer;
2.  Locate the coupon under **"Overview"**;
3.  Click the **bin icon** on the right; and
4.  Click **"Remove coupon"** to confirm.

The coupon will instantly disappear from the customer view and will not be
applied to the next invoice.


# Credit notes



<Info>
  **PREMIUM FEATURE** ✨

  Lago may automatically generate a credit note when a subscription is upgraded or
  downgraded. However, only users with a premium license can manually generate
  credit notes via the user interface or the API. Please
  **[contact us](mailto:hello@getlago.com)** to get access to Lago Cloud and Lago
  Self-Hosted Premium.
</Info>

Issue a credit note to refund or credit a `finalized` invoice back to your customer’s account.
Credit notes can be issued for all types of invoices. However, please note that credit notes cannot be issued for prepaid credit purchases that have already been consumed or are linked to a terminated wallet.

## Access credit notes creation flow[](#create-credit-notes "Direct link to heading")

<Info>
  Credit notes can only be issued for invoices with the status `finalized` and
  an amount greater than zero.
</Info>

To create a credit note through the user interface:

1.  Go to the **"Customers"** section;
2.  Select a customer to open the customer view;
3.  Open the **"Invoices"** tab;
4.  Click an invoice to see its details; and
5.  Select **"Issue a credit note"** from the **"Actions"** dropdown (upper right corner).

The credit note creation process varies depending on the payment status of the
invoice:

*   If the payment status of the invoice is `pending` or `failed`, the credit note
    will allow you to credit back the customer's account; and
*   If the payment status of the invoice is `succeeded`, the credit note will
    allow you to credit back the customer's account and/or refund them.

<Info>
  For prepaid credits invoices, credit notes can only be issued for invoices with a `succeeded` payment status. These credit notes are refundable only for this type of invoice and will directly void prepaid credits in the associated wallet.
</Info>

<Info>
  On subscription invoices, prepaid credits and credit notes applied cannot be refunded. These can only be credited back to the customer's account balance. Coupons are non-refundable and cannot be credited back to the customer's account.
</Info>

## Issue a credit note

<Tabs>
  <Tab title="Dashboard">
    1.  Select a reason from the list (e.g. duplicate charge, order cancelation,
        etc.);
    2.  Add an internal note (optional);
    3.  Select the item(s) and enter the amount(s) you want to credit;
    4.  Select the credit method(s) (only available for paid invoices -
        [learn more](#credit-methods)); and
    5.  Click **"Issue credit note"** to confirm.

    <Info>
      For each item, you must enter a credit amount equal to or less than the
      initial amount of the item, excluding tax. The total amount of the credit note
      cannot exceed the total amount of the invoice.
    </Info>
  </Tab>

  <Tab title="API">
    ```bash Create a credit note
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/credit_notes" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "credit_note": {
          "invoice_id": "**LAGO_INVOICE_ID**",
          "reason": "duplicated_charge",
          "credit_amount_cents": 10,
          "refund_amount_cents": 5,
          "items": [
            {
              "fee_id": "__LAGO_FEE_ID__",
              "amount_cents": 10
            },
            {
              "fee_id": "__LAGO_FEE_ID__",
              "amount_cents": 5
            }
          ]
        }
      }'

    ```
  </Tab>
</Tabs>

When the credit note is created, it will appear below the original invoice on
the invoice details page and in the **"Credit notes"** tab of the customer view.
In addition to this, a `credit_note.created` [webhook](/api-reference/webhooks/messages)
will automatically be sent by Lago.

You can link several credit notes to an invoice. Like invoices, credit notes
have a unique number and can be downloaded in PDF format.

<Frame caption="Credit note detail">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/credit-note-39fd904adb8cc192e4e78320171c388f.png" />
</Frame>

## Credit methods[](#credit-methods "Direct link to heading")

### Refund[](#refund "Direct link to heading")

When a credit note involves a refund, the amount of the refund will be included in the `credit_note.created` [webhook](/api-reference/webhooks/messages), which allows you to proceed with the payment.

The credit note will also contain a `refund_status` field, which can be set to `pending`, `succeeded`, or `failed`. You can update the refund status via the API.

Refunding a prepaid credit invoice will automatically void the corresponding prepaid credits in the active wallet.

<Tip>
  If you use one of our native payment integrations, the refund process will
  automatically be triggered by Lago.
</Tip>

### Credit note wallet[](#credit-note-wallet "Direct link to heading")

The amount of the credit note that is not refunded is credited to the customer's
account via a credit note wallet. The credit amount is included in the
`credit_note.created` [webhook](/api-reference/webhooks/messages) and displayed on the
credit note details page.

<Info>
  A credit note wallet is linked to a single credit note and therefore, to a
  single invoice. If there are several credit notes linked to the customer's
  account, Lago will create a credit note wallet for each of them.

  Credit note wallets are different from wallets associated with [prepaid credits](/guide/wallet-and-prepaid-credits).
</Info>

The total amount available in the credit note wallets will be deducted from the
subtotal of the customer's next invoice(s), after tax (see below).

```

## EXAMPLE OF INVOICE

All subscriptions = $50
All usage-based fees = $20
Coupons = $10

---

Subtotal (excl. tax) = $60
Tax (10%) = $ 6

---

Subtotal (incl. tax) = $66
Credit notes = $20
Prepaid credits = $30

---

Total due = $16

```

When the credit note wallet is created, the initial `credit_status` is
`available`. Then when the amount of the credit note wallet is zero, the status
switches to `consumed`.

## Void available credit[](#void-credit-note "Direct link to heading")

You can void the available credit linked to a specific credit note. To do so:

<Tabs>
  <Tab title="Dashboard">
    1.  Go to the **"Customers"** section;
    2.  Select a customer to open the customer view;
    3.  Open the **"Credit notes"** tab;
    4.  Click a credit note to see its details; and
    5.  Select **"Void credit available"** from the **"Actions"** dropdown (upper
        right corner).

    <Warning>
      When voiding a credit note wallet, the remaining credit amount will be lost
      and the `credit_status` will switch to `voided`. This action cannot be
      canceled.
    </Warning>
  </Tab>

  <Tab title="API">
    ```bash Void a credit note
    LAGO_URL="https://api.getlago.com"
    CREDIT_NOTE_ID="__YOU_CREDIT_NOTE_ID__"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request PUT "$LAGO_URL/api/v1/credit_notes/$CREDIT_NOTE_ID/void" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json'
    ```
  </Tab>
</Tabs>


# Customer management



## Create and update a customer[](#create-and-update-a-customer "Direct link to heading")

<Tabs>
  <Tab title="Dashboard">
    To create a customer through the user interface:

    1.  Access the **"Customers"** section via the side menu;
    2.  In the upper right corner, click **"Add a customer"**;
    3.  Enter the customer's name and external ID (i.e. unique ID as defined in your
        backend system);
    4.  Select the customer's timezone (optional -
        [learn more](/guide/customers/invoice-customer#bill-following-your-customers-timezone));
    5.  Enter the customer's billing information, including company information and
        address (optional);
    6.  Select the default payment provider for this customer (optional -
        [learn more](/guide/payments/overview)); and
    7.  Click **"Create customer"** to confirm.
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Create or update a customer
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
         "customer": {
            "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
            "address_line1": "5230 Penfield Ave",
            "address_line2": "",
            "city": "Woodland Hills",
            "country": "US",
            "currency": "EUR",
            "email": "dinesh@piedpiper.test",
            "legal_name": "Coleman-Blair",
            "legal_number": "49-008-2965",
            "tax_identification_number": "EU123456789",
            "logo_url": "http://hooli.com/logo.png",
            "name": "Gavin Belson",
            "phone": "1-171-883-3711 x245",
            "state": "CA",
            "timezone": "Europe/Paris",
            "url": "http://hooli.com",
            "zipcode": "91364",
            "tax_codes": [],
            "billing_configuration": {
               "invoice_grace_period": 3,
               "payment_provider": "stripe",
               "provider_customer_id": "cus_12345",
               "sync": true,
               "sync_with_provider": true,
               "document_locale": "fr",
            }
            "metadata": [
            {
               "key": "Name",
               "value": "John",
               "display_in_invoice": true
            }
            ]
         }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

Once a customer is created, you can access the customer view, where you can edit their information.

<Warning>
  You cannot change the `external_id` and the `currency` of customers after an object has been
  assigned to them (i.e. plans, coupons, one-off invoices, wallet and credits).
</Warning>

## Companies vs Individuals

When creating or updating a customer, you can specify whether the customer is a `company` or an `individual` by setting the customer type.
By default, if no customer type is specified, the customer will be created without a defined type, and you will need to assign one manually.

## Assign objects to a customer[](#assign-objects-to-a-customer "Direct link to heading")

The usage monitoring and billing processes start when you assign a plan to a
customer, which triggers a [subscription](/guide/subscriptions/assign-plan).

You can also apply [coupons](/guide/coupons), [one-off invoices](/guide/one-off-invoices/create-one-off-invoices) and
[prepaid credits](/guide/wallet-and-prepaid-credits) to a customer account.

To assign objects to a customer through the user interface:

1.  Access the **"Customers"** section via the side menu;
2.  Select a customer from the list;
3.  In the upper right corner of the customer view, click **"Actions"**; and
4.  Select an action from the dropdown list.

## Monitor the customer's current usage[](#monitor-the-customers-current-usage "Direct link to heading")

When a plan that includes usage-based charges is assigned to a customer, you can
start pushing [events](/guide/events/ingesting-usage) associated with the customer account.

During the billing period, the customer's current usage is visible in the
**"Analytics"** tab of the customer view, under **"Current usage report** including (but not limited to):

*   Total amount for the period under consideration; and
*   Breakdown by charge, including total number of billing units and amount.

<Tabs>
  <Tab title="Dashboard">
    <Frame caption="Fetch customer's current usage">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/customer-current-usage.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    You can retrieve the customer's current usage via the API using [this endpoint](/api-reference/customer-usage/get-current).

    <CodeGroup>
      ```bash Get customer current usage
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"
      EXTERNAL_CUSTOMER_ID="5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"
      EXTERNAL_SUBSCRIPTION_ID="sub_1234567890"

      curl --location --request GET "$LAGO_URL/api/v1/customers/$EXTERNAL_CUSTOMER_ID/current_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Monitor the customer's billing status[](#monitor-the-customers-overdue-balance "Direct link to heading")

The "**Billing overview**" lets you see in a glance where a customer stands in terms of revenue and collection. It takes into account invoices since the customer's creation date.

*   Gross revenue indicates how much has been billed to this customer
*   Total overdue highlights the aggregated amount from invoices that are past due

<Tabs>
  <Tab title="Dashboard">
    <Frame caption="Check a customer's billing status">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/customer-billing-overview.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    You can retrieve the customer's gross revenue via the API using [this endpoint](/api-reference/analytics/gross-revenue).

    <CodeGroup>
      ```bash Get customer gross revenue
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request GET "$LAGO_URL/api/v1/analytics/gross_revenue?external_customer_id=hooli_1234&currency=USD" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \  
      ```
    </CodeGroup>

    You can retrieve the customer's overdue balance via the API using [this endpoint](/api-reference/analytics/overdue-balance).

    <CodeGroup>
      ```bash Get customer overdue balance
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request GET "$LAGO_URL/api/v1/analytics/overdue_balance?external_customer_id=hooli_1234&currency=USD" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \  
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Deleting a customer

You may delete a customer linked to existing objects (i.e. applied coupons, wallets, subscriptions, add-ons).

If you do so:

*   All [subscriptions](/guide/subscriptions/assign-plan) associated with this customer account will be immediately terminated (this action may trigger the generation of invoices and/or credit notes);
*   All [coupons](/guide/coupons) applied to this customer account will be immeditely terminated;
*   The customer's active [wallet](/guide/wallet-and-prepaid-credits) will be immediately terminated and all remaining credits will be voided; and
*   All `draft` invoices associated with this customer account will be immediately finalized.

`finalized` invoices and [credit notes](/guide/credit-notes) associated with the deleted customer remain available in the **"Invoices"** section of the user interface and can also be retrieved via the API.

It is possible to generate new credit notes and process refunds after the deletion of the customer.

<Info>
  After deleting a customer account, you can create a new one using the same `external_id`.
</Info>


# Customer metadata



## Add metadata on customer

Metadata on customer is useful for storing additional structured information on an object to provide more context.

For example, you could store a customer's full name and unique identifier from your system on a Customer object by defining a key-value pair. A key cannot exist without its corresponding value, and vice versa.

## Edit and delete metadata on customer

After adding metadata to a customer, you can edit or delete it. To edit metadata, you have two options:

1.  Use the user interface to update the information displayed in the "Edit customer" drawer, and then save the customer changes.
2.  Use the API to target the key-value pair information with the metadata ID in your code snippet and edit the key and value.

<Info>
  When editing customer metadata through the API, make sure to include the existing metadata in your payload to avoid removing them.
</Info>

Similarly, you can delete a key-value metadata pair by:

1.  Clicking on the trash icon in the user interface, and then saving the customer changes.
2.  Removing the key-value metadata object from your code snippet when using the API.

## Display metadata in invoice object

To display customer metadata on invoices, you can switch on the option in the customer creation/edition drawer or set `display_in_invoice` to true. Once this option is activated, metadata will be displayed on all new finalized and downloaded invoices.

<Info>
  When the customer's metadata is added/edited/removed, the change only applies to new PDF files. Existing documents are not affected.
</Info>

## Customer metadata limitiation

1.  We are limiting the number of metadata on customers to 5.
2.  Keys must be strings under 20 characters.
3.  Values must be strings under 40 characters.


# The customer portal



The Lago Customer Portal is a user-friendly platform that allows you to effortlessly share billing information, such as past invoices, with your end customers. As we continue to develop this tool, you will be able to display even more useful information to your customers.

## Generate a customer portal link

To generate a customer portal URL that can be embedded into your product, you have two options:

1.  Use the [API endpoint](/api-reference/customers/customer-portal); or
2.  Click the Customer Portal link on a specific customer details view.

<Frame caption="Customer portal access">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/customer-portal-access.png" />
</Frame>

## Embedding the dashboard

You can also use the API to generate an embeddable Customer Portal that can be displayed in your application by using an iframe. To do so, use the endpoint `/customers/:external_customer_id/portal_url` to generate an embeddable URL that can be displayed in your user interface.

<Info>
  For security reasons, the token returned by the API **expires after 12 hours**. Therefore, it is important to use the endpoint and generate a new token every time a customer refreshes or accesses the billing page.
</Info>

## Customer portal preferred language

By default, the embedded portal is displayed in English. However, you can easily change the language for a specific customer by adjusting the `document language` in their settings. To access this feature, follow these simple steps:

To access document language settings:

1.  Go to the specific customer's profile;
2.  Click the **Settings** tab;
3.  **Edit** the document language section; and
4.  Select the preferred language.

You can also update the language of a customer directly from the API.

<Info>
  If the language you are looking for is not yet available, please [visit this page](/api-reference/resources/locales).
</Info>

## Customer portal information

### 1. Invoice history

The invoice history section provides a summary of both total invoices (everything that has been invoiced since the beginning) and overdue invoices (all the invoices past their due date, which are due). Your customers can know where they stand in one glance.

The Customer Portal allows your customers to retrieve all past invoices and download them with ease. Lago displays useful billing information such as the issuing date, invoice number, amount, and payment status (paid or unpaid). Additionally, your customers can filter the list and search for a specific invoice.

<Frame caption="Invoices list - Customer Portal">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/customer-portal-invoices-list.png" />
</Frame>

### 2. Customer information

In addition to viewing their invoice list, customers can retrieve essential billing information, including legal name, tax identification number, billing email, and billing/shipping addresses.

Customers can also update this information directly through the portal, ensuring that their billing details remain synchronized with the latest data.

<Frame caption="Customer information - Customer Portal">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/customer-information-portal.png" />
</Frame>

### 3. Plans and usage information

In addition to viewing their invoices and customer details, customers can access their subscriptions and usage directly through the portal.

For subscription details, they can view key information such as the plan name, recurring fee, and subscription renewal date.

Customers also have real-time access to comprehensive usage details, including:

*   Total lifetime usage and the next threshold for subscriptions using progressive billing;
*   A detailed usage report, showing the number of units consumed and associated costs; and
*   A full breakdown of usage by billing filters and groups.

<Frame caption="Plans and usage - Customer Portal">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/plans-usage-portal.png" />
</Frame>

### 4. Prepaid credits information

The customer portal provides your customers with real-time access to their prepaid credit balance, showing the remaining credits based on their current usage.

Additionally, customers can top up their paid credits, ensuring their wallet is always sufficiently funded.

<Frame caption="Prepaid credits - Customer Portal">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/prepaid-credits-portal.png" />
</Frame>


# Invoice a customer



If a customer has an active subscription, Lago will automatically generate an [invoice](/guide/invoicing/overview) for them at the end of the billing period.

## Bill following your customer's timezone

<Info>
  **Premium feature ✨**:

  The timezone feature is only available to users with a premium license. Please **[contact us](mailto:hello@getlago.com)** to get access to Lago Cloud and Lago Self-Hosted Premium.
</Info>

The beginning and end of the billing period depend on the timezone applied to the customer account. The default timezone is UTC but you can define another timezone for your organization, which can be overwritten by the customer's timezone.

<Tabs>
  <Tab title="Dashboard">
    To set the customer's timezone through the user interface:

    1.  Access the **"Customers"** section via the side menu;
    2.  Select a customer from the list;
    3.  In the **"Overview"** tab of the customer view, click **"Edit"** above the customer details;
    4.  Select a timezone from the list; and
    5.  Click **"Edit customer information"** to confirm.
  </Tab>

  <Tab title="API">
    You can define a specific timezone by using the `timezone` field on a customer.

    <CodeGroup>
      ```bash Set a customer timezone {23}
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
          "customer": {
            "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
            "address_line1": "5230 Penfield Ave",
            "address_line2": "",
            "city": "Woodland Hills",
            "country": "US",
            "currency": "EUR",
            "email": "dinesh@piedpiper.test",
            "legal_name": "Coleman-Blair",
            "legal_number": "49-008-2965",
            "tax_identification_number": "EU123456789",
            "logo_url": "http://hooli.com/logo.png",
            "name": "Gavin Belson",
            "phone": "1-171-883-3711 x245",
            "state": "CA",
            "timezone": "Europe/Paris",
            "url": "http://hooli.com",
            "zipcode": "91364",
            "billing_configuration": {
              "invoice_grace_period": 3,
              "payment_provider": "stripe",
              "provider_customer_id": "cus_12345",
              "sync": true,
              "sync_with_provider": true,
              "document_locale": "fr",
              "vat_rate": 12.5
          },
          "metadata": [
            {
              "key": "Name",
              "value": "John",
              "display_in_invoice": true
            }
          ]
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

The dates displayed in the **"Usage"**, **"Invoices"** and **"Credit notes"** tabs of the customer view are based on the customer's timezone.

<Tip>
  You can hover over any date in the customer view to see the reference timezones.
</Tip>

## Preferred language

The default language for documents is defined at the organization level ([learn more](/guide/invoicing/download-invoices#translate-invoices)). It can be overwritten at the customer level.

<Tabs>
  <Tab title="Dashboard">
    To set the customer's preferred language:

    1.  Access the **"Customers"** section via the side menu;
    2.  Select a customer from the list;
    3.  Open the **"Settings"** tab;
    4.  Click **"Add a language"**;
    5.  Select a language from the list; and
    6.  Click **"Add language"** to confirm.
  </Tab>

  <Tab title="API">
    You can define a specific preferred language by using the `document_locale` field on a customer, inside the `billing_configuration` object.

    <CodeGroup>
      ```bash Set a customer preferred language {32}
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "customer": {
          "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "address_line1": "5230 Penfield Ave",
          "address_line2": "",
          "city": "Woodland Hills",
          "country": "US",
          "currency": "EUR",
          "email": "dinesh@piedpiper.test",
          "legal_name": "Coleman-Blair",
          "legal_number": "49-008-2965",
          "tax_identification_number": "EU123456789",
          "logo_url": "http://hooli.com/logo.png",
          "name": "Gavin Belson",
          "phone": "1-171-883-3711 x245",
          "state": "CA",
          "timezone": "Europe/Paris",
          "url": "http://hooli.com",
          "zipcode": "91364",
          "billing_configuration": {
              "invoice_grace_period": 3,
              "payment_provider": "stripe",
              "provider_customer_id": "cus_12345",
              "sync": true,
              "sync_with_provider": true,
              "document_locale": "fr",
              "vat_rate": 12.5
          },
          "metadata": [
            {
              "key": "Name",
              "value": "John",
              "display_in_invoice": true
            }
          ]
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

Please refer to the API documentation to see the [list of supported languages](/api-reference/resources/locales).

<Info>
  When the customer's preferred language is updated, the change only applies to new PDF files. Existing documents are not affected.
</Info>


# Automatic dunning

Automate how to communicate with your customers to remind them of overdue invoices and attempt to recover their overdue balance using dunning campaigns.

<Info>
  **PREMIUM ADD-ON** ✨

  This feature is available upon request only. Please **[contact us](mailto:hello@getlago.com)** to get access to this premium feature.
</Info>

## Create campaigns

Automatic dunning relies on the concept of dunning campaign, which then can be applied at the organization level, or per customer. You can create several campaigns to accommodate different needs: different thresholds or different cadences for instance. The goal of a campaign is to collect payment for a customer's overdue balance.

<Frame caption="Set dunning at the organization level">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/dunning/images/dunning_org_level.png" />
</Frame>

Follow these steps to create a new campaign

1.  Access the dunning settings page through the **Settings** section > **Dunning** tab;
2.  In the **Dunning campaigns** section, click **“Add”** to create a new campaign;

### Campaign settings

These settings allow you to identify a campaign.

1.  Enter its **`name`**;
2.  Assign it a unique **`code`** (i.e. unique ID as defined in your backend system); and
3.  Add a **`description`** *(optional).*

### Trigger settings

These settings define when a campaign should start running for a customer.

4.  Define an **`overdue balance threshold`.**

At least one threshold is required to be able to save a campaign.

You can define as many thresholds as currencies you support. When a dunning campaign applies to a customer, as soon as they reach this threshold, the campaign will launch for this customer.

If a customer is invoiced in a currency that you don't support in your dunning campaign, they won't be eligible to this dunning campaign.

### Attempt settings

5.  You can **`preview the email`** sent in case no payment provider is linked, or if the payment from an attempt fails.
6.  Add **`a delay between attempts`,** in days.

The first attempt of a dunning campaign will happen when the overdue balance threshold is met. The next attempts will be triggered after the delay you have set.

7.  Decide to **`End the flow after`** a number of attempts.

### Default campaign for your organization

8.  You can choose to **`Set as default campaign for your organization`**.

<Frame caption="Create a dunning campaign">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/dunning/images/dunning_create_campaign.png" />
</Frame>

## Automatic dunning at the organization level

When defining a default campaign at the organization level, the campaign will apply to all customers inheriting the organization dunning behavior, except those for whom:

*   a specific campaign has been applied,
*   dunning has been deactivated.

It is possible to have no campaign defined as default for the organization, and apply dunning campaigns independently to each customer.

This setting is also available from the list of dunning campaigns, from where you can directly set a campaign as default for the organization.

## Automatic dunning at the customer level

If a campaign has been set as default for the organization, by default it will apply to all customers. You can chose to override this behavior at the customer level.

1.  Access the customer settings page through the **Customer** details page > **Settings** tab;
2.  In the **Dunning** section, click **“Edit”** to change the dunning behavior;
3.  Select the behavior you want to apply.

<Frame caption="Apply a dunning campaign at the customer level">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/dunning/images/dunning_customer_level.png" />
</Frame>

### Fallback to default dunning behavior from organization

The behavior defined at the organization level will prevail: either a campaign is applied, or no dunning is set.

### Apply a specific campaign for a customer

Only the campaigns with a threshold defined in the customer's currency are available.
The campaign will apply as soon as the behavior is saved, and the customer will no longer listen to what has been defined at the organization level.

#### Deactivate dunning

No automatic dunning attempt will impact this customer, whether it is the default organization campaign or a campaign applied at the customer level.

You can still trigger manual duning requests for the customer.

<Frame caption="Apply a dunning campaign at the customer level">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/dunning/images/dunning_edit_behavior.png" />
</Frame>

### Change from one campaign to another

If you change the default campaign to apply another, or if you change the campaign applied to a customer, dunning could running for some customers. In that case the current campaign will be stopped, and the new campaign will take precedence and start from zero.

## Behavior of a campaign

Once a campaign is applied to a customer:

1.  Its threshold will be monitored.
2.  When the customer's overdue balance reaches the threshold, a first payment request will be triggered during the coming hour. Depending if a payment provider is available for the customer or not, a payment intent and/or an email will be triggered.
3.  If a second attempt is planned, after the defined delay the overdue balance will be checked again. If still above the threshold, a new attempt will be triggered. New attempts will be triggered this way until the maximum number of attempts defined is reached.
4.  If reaching the end of the planned attempts, the dunning campaign will be considered as completed. No further attempts will be triggered, unless the campaign applied to the customer is changed.

### A payment provider is connected for the customer

A payment intent will be generated for the amount shown.

*   If the payment fails, and email will be sent requesting payment, with a URL to pay (except for Gocardless where no payment URL is provided).
*   When the payment is successful, the attached invoices will automatically be updated with a succeeded payment status.

### No payment provider is available for the customer

An email will be sent requesting payment for the overdue balance.

*   When the payment is successful, you will have to manually update the payment status of said invoices.


# Manual dunning

Dunning refers to the process of communicating with customers to remind them of overdue invoices and attempt to recover the outstanding amounts.

## Overdue balance payment

When a customer has some invoices past their due date, their [overdue balance](https://docs.getlago.com/guide/customers/customer-management#monitor-the-customers-billing-status) becomes positive, and you have the ability to request its payment manually.

<Info>
  **Premium feature ✨**

  This feature is only available to users with a premium license. Please **[contact us](mailto:hello@getlago.com)** to get access access to Lago Cloud and Lago Self-Hosted Premium.
</Info>

<Tabs>
  <Tab title="Dashboard">
    In the customer view, a "request payment” link appears within the overdue balance warning.

    <Frame caption="Request payment for the overdue balance">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/customer-request-overdue-balance-payment.png" />
    </Frame>

    By clicking on it, a panel opens so you can:

    *   Review the invoices included in the overdue balance,
    *   Review the email which will be sent in case the payment fails, or if no payment provider is linked
    *   Confirm you want to request the payment.

    <Frame caption="Preview the overdue balance payment request">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/customer-overdue-balance-payment-preview.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    You can create a payment request for the overdue balance from the API, targeting the invoices you want to be paid.

    <CodeGroup>
      ```bash Create a payment request
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/payment_requests/" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        {
        "payment_request": {
          "lago_invoice_ids": ["4064eff9-e7a6-4692-a289-15d7d5da9b83", "b1f36d2f-8ea6-4192-9407-8e87ba5c28c2"],
          "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "email": "rebecca@piedpiper.test"
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## A payment provider is connected for this customer

A payment intent will be generated for the amount shown.

*   If the payment fails, and email will be sent requesting payment, with a URL to pay (except for Gocardless where no payment URL is provided).
*   When the payment is successful, the attached invoices will automatically be updated with a succeeded payment status.

## No payment provider is available for this customer

An email will be sent requesting payment for the overdue balance.

*   When the payment is successful, you will have to manually update the payment status of said invoices.


# Emails

Send automatic emails when issuing an invoice or any billing documents.

<Info>
  **PREMIUM FEATURE** ✨

  Only users with a premium license can automatically send emails from Lago to their customers. Please **[contact us](mailto:hello@getlago.com)** to get access to Lago Cloud and Lago Self-Hosted Premium.
</Info>

With Lago, sending invoices and credit notes to your customers is simple - you can automatically email them as soon as they are created.

<Warning>
  Lago will never ask for payment details or personal information.
</Warning>

## SMTP setup on Lago Cloud

You don't have to worry about SMTP settings with Lago, we take care of it, so you can sit back and relax.

## SMTP setup on Lago Self-hosted Premium

In order to use the email feature, please configure your environment variables [as described here](/guide/self-hosted/docker#smtp-configuration).

## Prerequisites for sending emails

To send emails to your customers, you will need to:

1.  Define an organization email in Settings > Organization;
2.  Optionally, add your organization’s logo in Settings > Organization;
3.  Turn on the relevant email scenarios; and
4.  Define the customer’s email address during customer creation/edition.
5.  To send invoices to multiple recipients, define multiple email addresses at the customer level, separated by commas.
    (e.g. `billing@acme.com`,`accounting@acme.com`,`finance@acme.com`)

## Email scenarios

Lago sends emails to your customers in two scenarios: when an invoice is finalized (i.e. subscription invoices, one-off invoices, invoices related to credit purchases), and when a credit note is issued for a customer.

By default, both scenarios are switched off. To turn these scenarios on/off:

1.  Go to Settings;
2.  Open the Emails tab;
3.  Toggle each scenario on/off; or
4.  Click on a scenario to see the corresponding email; and
5.  Use the toggle in the upper-right corner to switch this scenario on/off.

<Info>
  To avoid sending too many notifications to customers, we have deactivated emails for invoices without fees.

  Although invoices with `"fees_amount_cents": 0` are not sent to customers by email, they are available in the database and user interface.
</Info>

## Email locale

The content of the email will be based on the organization or customer's document locale. This means that the email will have the same locale as the invoice sent.

## Email sending address

For the cloud version, Lago uses [no-reply@getlago.com](mailto:no-reply@getlago.com) as the sending email address. Any responses from your customers will be directed to the email address you have established for your organization in the organization settings.

## Email template

<Frame caption="Email template">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/email-template.png" />
</Frame>

As mentioned above, some information in the email template can be customized based on the settings of your account, including:

1.  The logo of your organization;
2.  The name of your organization; and
3.  The email address of your organization.


# Entitlements



Lago partners with [Oso](https://osohq.com) to provide the best-in-class Entitlements solution.

[Oso](https://www.osohq.com/)  is an authorization-as-a-service provider partnering with Lago to offer entitlements. You can use either the open-source version (available on [Github](https://github.com/osohq/oso)) or the cloud-hosted version. To create entitlements with Lago, you must open an account on Oso.

Oso offers a suitable solution for Entitlements. For more information, please refer to [Oso's documentation](https://www.osohq.com/docs/guides/model/entitlements).

## Define available features and plan's quota

First, define the available features for each plan. For instance, the Basic plan has a limited set of features, while the Premium plan offers the full range.

In addition to this, you can use Lago to bill metering and overage. This information can then be passed directly to Oso's `plan_quota` and `quota_used` to limit usage for a specific feature.

## Example

[Oso's documentation](https://www.osohq.com/docs/guides/model/entitlements) explains the following example of entitlements properly.

```ruby
actor User { }
 
resource Organization {
    roles = ["admin", "member"];
    permissions = ["create_repository"];

    "member" if "admin";
}
 
 
resource Plan { 
    roles = ["subscriber"];
    relations = { subscribed_organization: Organization };
    
    "subscriber" if role on "subscribed_organization";
}
 
resource Feature {
    relations = { plan: Plan };
}
 
declare plan_quota(Plan, Feature, Integer);
declare quota_used(Organization, Feature, Integer);
 
plan_quota(Plan{"pro"}, Feature{"repository"}, 10);
plan_quota(Plan{"basic"}, Feature{"repository"}, 0);
 
has_quota_remaining(org: Organization, feature: Feature) if
    has_quota(org, feature, quota) and
    quota_used(org, feature, used) and
    used < quota;
 
has_quota(org: Organization, feature: Feature, quota: Integer) if
    plan matches Plan and
    has_relation(plan, "subscribed", org) and
    plan_quota(plan, feature, quota);
 
 
has_permission(user: User, "create_repository", org: Organization) if
    has_role(user, "member", org) and
    has_quota_remaining(org, Feature{"repository"});
 
 
 
test "members can create repositorys if they have quota" {
    setup {
        quota_used(Organization{"apple"}, Feature{"repository"}, 5);
        quota_used(Organization{"netflix"}, Feature{"repository"}, 10);
        quota_used(Organization{"amazon"}, Feature{"repository"}, 0);
        has_relation(Plan{"pro"}, "subscribed", Organization{"apple"});
        has_relation(Plan{"pro"}, "subscribed", Organization{"netflix"});
        has_relation(Plan{"basic"}, "subscribed", Organization{"amazon"});
        has_role(User{"alice"}, "member", Organization{"apple"});
        has_role(User{"bob"}, "member", Organization{"netflix"});
        has_role(User{"charlie"}, "member", Organization{"amazon"});
    }
    assert has_quota_remaining(Organization{"apple"}, Feature{"repository"});
    # Apple has quota remaining, so all good
    assert allow(User{"alice"}, "create_repository", Organization{"apple"});
    # Netflix has used all quota 
    assert_not allow(User{"bob"}, "create_repository", Organization{"netflix"});
    # Amazon doesn't have any quota left
    assert_not allow(User{"charlie"}, "create_repository", Organization{"amazon"});
}
```


# Events list

By ingesting events, you can see them flowing in the Lago application by using the events list. It allows you to take a deeper look at ingested events and detect possible warnings.

## Accessing the events list[](#accessing-the-events-list "Direct link to heading")

You can access the events list from the UI by following this path:

1.  Go to the **Developers** section in the sidebar;
2.  Click the **events** tab;
3.  See a list of ingested events; and
4.  Reload this list when you ingest new events.

By default, the UI shows you a list of the latest 20 events, but you can load
much more by scrolling down the page.

<Tip>If an event is not shown in the UI, it has **not** been ingested.</Tip>

<Frame caption="Accessing the events list">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/events/images/events-debugger-6bcbcf7e46f1bd4bb8a9b6e6964bba69.png" />
</Frame>

## Accessing a specific event[](#accessing-a-specific-event "Direct link to heading")

In the events list view, by clicking on a specific event, you will have access to 2 main
blocks:

1.  **A list of useful properties returned**
    *   **Time:** timestamp of the received events;
    *   **Customer ID:** the ID of your customer;
    *   **Billable metric code:** code of the billable metric linked to the event;
    *   **Billable metric name:** name of the billable metric linked to the event;
    *   **Transaction ID:** unique `transaction_id` of the event used as
        idempotency key;
    *   **IP Address:** IP address of the event sender; and
    *   **Client API:** Lago Client API used to send the event.
2.  **A JSON with event's arguments sent in the payload**

## Possible warnings[](#possible-warnings "Direct link to heading")

Some events can be ingested but triggering a bad or unexpected behavior. This is
why Lago displays in the UI two possible warnings:

1.  The event `code` is **not related to an existing billable metric**; and
2.  The billable metric's **property used for the aggregation is not sent**
    through this event.


# Ingesting usage

This guide explains how Lago ingests usage-based events coming from your application.

## Define a billable metric[](#define-a-billable-metric "Direct link to heading")

**Usage events are designed to target very specific
[billable metrics](/guide/billable-metrics/create-billable-metrics) created from the UI**. If you don't understand the
concept of billable metrics, we recommend you to read it first.

First things first, you need to define a billable metric from the UI to send
usage measurement events:

1.  In the Lago app, go to the **"Billable metrics"** section;
2.  Click **"Add a billable metric"**;
3.  Add metric information, including:
    *   `name`
    *   `code` (used to send events via API)
    *   `description` (optional)
4.  Define whether or not this metric is `recurring`; and
5.  Choose an aggregation type to define how usage should be calculated.

Billable metrics represent the features of your product. Events should automatically be sent to Lago by your application
based on your customers' actions.

## Send usage measurements to Lago[](#send-usage-measurements-to-lago "Direct link to heading")

To send usage events to Lago, you need to use the **Lago API**. A measurement
event is JSON with the following fields:

```json
{
  "transaction_id": "__TRANSACTION_ID__" // (Required) Unique identifier of the event
  "external_subscription_id": "__SUBSCRIPTION_ID__" // (Required) Unique identifier of your customer's subscription
  "code": "__EVENT_CODE__", // (Required) The billable metric's code
  "timestamp": 1650893379, // (Required) UNIX timestamp of the event
  "precise_total_amount_cents": "140", // (Optional) Precise amount cents of the event used for dynamic charge model
  "properties": {
    "custom_field": 12, // (Optional) Custom variables defined as properties
    "operation_type": "add" or "remove" // (Optional) Required only for recurring metric based on the unique count aggregation
  }
}
```

<AccordionGroup>
  <Accordion title="1. The transaction_id">
    The `transaction_id` is very useful to ensure the uniqueness of the events
    received. It is mandatory to define on your own a unique `transaction_id` for
    each event you send to Lago.

    This identifier is used to deduplicate events ingested, making sure we don't
    ingest twice the same event (otherwise, this could create billing errors for
    your customers).

    *   If a `transaction_id` is new to Lago, the event is ingested;
    *   If a `transaction_id` has already been received by Lago, it's ignored.

    <Tip>
      **Good practice:**
      Send the id of the transaction coming from your backend.
      If you do not have an existing id for a transaction, you can create a unique one
      by concatenating the `code` of the Billable metric and the `timestamp` of the
      event \*(example: `api_searches_2022-04-01T03:49:23Z`).
    </Tip>
  </Accordion>

  <Accordion title="2. The external_subscription_id">
    This attribute allows Lago to assign the event to the right subscription (and therefore to the right customer).
    The `external subscription_id` is required, as it ensures accurate billing.
  </Accordion>

  <Accordion title="3. The event code">
    The event `code` represents the unique code of the Billable metric you want to
    start ingest measurements on. This code is required for all events received in
    Lago. For instance, you can start ingesting events for Billable metrics with
    codes `api_seaches` *(for api products example)*, `storage` *(cloud companies
    example)*, `atm_withdrawals` *(fintech example)*, or anything you need to define
    as a paying feature.
  </Accordion>

  <Accordion title="4. The event timestamp">
    The event timestamp is the date when the billing event occurs in your
    application and sent to Lago. This event must be a
    **[UNIX Timestamp](https://www.unixtimestamp.com/).** For instance, you could
    define `1650893379` for *Mon Apr 25 2022 13:29:39 GMT+0000* or `1651682217`for
    *Wed May 04 2022 16:36:57 GMT+0000*.

    **This `timestamp` is not mandatory to send the event**. If you do not specify a
    timestamp on your own, Lago automatically defines the reception date of the
    event as the event timestamp.
  </Accordion>

  <Accordion title="5. The event precise amount cent">
    The event’s precise amount in cents refers to the amount sent to Lago when using a dynamic charge model.
    This value must be specified in cents.

    **The precise\_total\_amount\_cents is not mandatory when sending the event.** If you do not specify an amount, Lago will automatically set it to 0, and the event will not be included in the charge aggregation.
  </Accordion>

  <Accordion title="6. The event properties">
    Event properties are useful to send more context in usage events. Moreover, they
    are also very useful when you need to aggregate a Billable metrics for `SUM`,
    `MAX` and `UNIQUE COUNT`. Event properties can be `strings`, `integers`,
    `floats`, `uuids` or `timestamps`.

    In case of an aggregation type `UNIQUE COUNT` for a metric that is `recurring`
    , the `operation_type` is required.
    By sending `add`, you will add a value. By sending `remove`, you will remove a value.
  </Accordion>
</AccordionGroup>

<Warning>
  If you were using the `external_customer_id` to send usage measurement, note
  that this field is deprecated and is no longer supported or maintained. Please
  use the `external_subscription_id` instead.
</Warning>

## Idempotency and retries[](#idempotency-and-retries "Direct link to heading")

By using a unique `transaction_id`, can send events to Lago as much as you want
without worrying about sending twice the same event. Duplicates will be ignored
by our system. This ensures that your customers' usage is counted once. In case
of duplicates, we guarantee that only one of the events will be ingested, and
the other ones are ignored.

In case you are not sure if an event has been ingested, we recommend you to send
it multiple times (or to replay it). Once again, with the uniqueness of the
`transaction_id`, your customers won't be badly affected.

## User action trigger or periodic trigger[](#user-action-trigger-or-periodic-trigger "Direct link to heading")

With Lago, you can define when you need to trigger events based on the actions
your customers make in your application. There are 2 ways of tracking billing
events with Lago.

### User action trigger[](#user-action-trigger "Direct link to heading")

Anytime a user perform an action in your product, this sends an event to Lago.
This can be useful for companies tracking usage with a lot of granularity. As we
do the math for you, you can send events whenever you need and don't compute
hard calculations on your own.

For instance, think of a *fintech company* tracking user action. Each time a
customer withdraw money at an ATM, you send an event to Lago. We aggregate the
usage of a billable period based on what you defined in a Billable metric called
`atm_withdrawals`.

### Periodic trigger[](#periodic-trigger "Direct link to heading")

Some companies, such as infrastructure or cloud ones, often use periodic
triggers to calculate consumption. Think of the example of a thermometer to
measure fever. We would probably track the temperature once per hour (at a
periodic time). This is the same for cloud companies selling computation. You
could send an event to Lago each single minute measuring the CPU consumption of
a customer.

## Batching events

In Lago, event batching allows for the efficient ingestion of multiple events through a single API call.
This capability enhances data throughput and reduces the number of API requests needed for event management.

*   **Batching multiple events:** Users can aggregate multiple events into a single batch. This consolidation enables the ingestion of numerous events simultaneously, significantly optimizing the data transmission process.
*   **API call limitation:** Lago supports batching of up to 100 events per API call. This feature is designed to balance between high-volume data handling and system performance.
*   **Validation process:** If any event within the batch does not meet the structural requirements, the entire batch will be rejected. This ensures data integrity and consistency. Users are advised to verify the structure of each event before batching to prevent rejections.

## Designed for flexibility[](#designed-for-flexibility "Direct link to heading")

Lago is designed to ingest a high number of events. By defining aggregation
rules, you can define any billing use cases your company might want to track.
Whether you need to send **[user action triggered](#user-action-trigger)**
events or **[periodic triggered](#periodic-trigger)** events, Lago does the math
on your own so you don't have to query heavy databases before charging your
customers.

## Next steps[](#next-steps "Direct link to heading")

Once you defined your Billable metrics (with their aggregation rules), and
started ingesting events to track usage, you are able to define how much your
customers will pay for it. This has to be specified in
**[Plans](/guide/plans/overview)**.


# Metering ingestion sources

Here is a list of sources you can use to ingest usage data. Some of these sources are capable of handling up to 15,000 events per second with default settings.

## Free sources

Here is the list of usage ingestion and metering sources available in the free version of Lago.

<CardGroup cols={2}>
  <Card title="HTTP Client">
    Establishes a connection to a server and continuously sends requests for a specific message.
  </Card>
</CardGroup>

## Premium sources

Here is the list of usage ingestion and metering sources available in the premium version of Lago.

<CardGroup cols={2}>
  <Card title="AWS Kinesis">
    Receives messages from multiple Kinesis streams.
  </Card>

  <Card title="AWS S3">
    Fetches objects from an S3 bucket, with optional prefix filtering, either by listing items or through real-time upload notifications.
  </Card>

  <Card title="AWS SQS">
    Retrieves and processes messages from an AWS SQS queue using a specified URL.
  </Card>

  <Card title="Azure">
    Transmits usage and metering data via Azure CosmosDB, Queue Storage, or Table Storage.
  </Card>

  <Card title="CockroackDB">
    Monitors a CockroachDB Core Changefeed and creates a message for each received row.
  </Card>

  <Card title="CSV Files">
    Reads data from one or more CSV files
  </Card>

  <Card title="Google Cloud Platform">
    Transmits usage and metering data via GCP Big Query or Cloud Storage bucket.
  </Card>

  <Card title="Kafka">
    Establishes a connection to Kafka brokers and consumes messages from one or more topics.
  </Card>

  <Card title="MongoDB">
    Runs a query in MongoDB and produces a message for every document returned.
  </Card>

  <Card title="Redis">
    Transmits usage and metering data via Redis Scan or Streams.
  </Card>

  <Card title="SQL">
    Transmits usage and metering data via SQL raw or select.
  </Card>

  <Card title="Websocket">
    Establishes a connection to a websocket server and continuously send usage for incoming messages.
  </Card>
</CardGroup>


# Retrieving usage

Learn how to retrieve usage data for both current and past billing periods.

## Retrieve current usage

Current usage fetches real-time customer data for the open billing period.
Keep in mind that since this period isn't closed yet, invoice details may evolve over time.

<RequestExample>
  ```bash Retrieve current usage
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"
  EXTERNAL_CUSTOMER_ID="__EXTERNAL_CUSTOMER_ID__"
  EXTERNAL_SUBSCRIPTION_ID="__EXTERNAL_SUBSCRIPTION_ID__"

  curl --location --request GET "$LAGO_URL/api/v1/customers/$EXTERNAL_CUSTOMER_ID/current_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json'
  ```
</RequestExample>

## Retrieve past usage

Retrieving historical customer usage data provides usage details for closed billing periods.
This data remains unchanged unless you're in a grace period, where past usage can be adjusted for a draft invoice.

<RequestExample>
  ```bash Retrieve past usage
  LAGO_URL="https://api.getlago.com"
  API_KEY="__YOUR_API_KEY__"
  EXTERNAL_CUSTOMER_ID="__EXTERNAL_CUSTOMER_ID__"
  EXTERNAL_SUBSCRIPTION_ID="__EXTERNAL_SUBSCRIPTION_ID__"

  curl --location --request GET "$LAGO_URL/api/v1/customers/$EXTERNAL_CUSTOMER_ID/past_usage?external_subscription_id=$EXTERNAL_SUBSCRIPTION_ID" \
  --header "Authorization: Bearer $API_KEY" \
  --header 'Content-Type: application/json'
  ```
</RequestExample>


# Integration testing

This step-by-step integration guide will help you get started with Lago.

## Foreword[](#foreword "Direct link to heading")

At the moment, each Lago account is associated with a unique environment. It is
currently not possible to have your test environment and production environment
in the same account.

However, we can suggest different workarounds:

1.  **Create two accounts** to get access to two environments, one that could be
    called "Company Staging" and another one that could be called "Company
    Production"; or
2.  **Leverage our two hosting solutions** to use Lago Cloud as a test
    environment and Lago Open Source as a production environment (or vice versa).

Please note that the above workarounds will require you to replicate the same
setup in both environments.

<Info>
  In the future, you will be able to get access to a test environment and a
  production environment with the same Lago account.
</Info>

## 1. Define a billable metric[](#1-define-a-billable-metric "Direct link to heading")

To define a billable metric through the user interface:

1.  In the side menu, select **"Billable metrics"**;
2.  Click **"Add a billable metric"** in the upper right corner;
3.  Fill in the form ([learn more about billable metrics](/guide/billable-metrics/create-billable-metrics)); and
4.  Click **"Add billable metric"** to save.

## 2. Create a plan (with charges)[](#2-create-a-plan-with-charges "Direct link to heading")

To create a plan through the user interface:

1.  In the side menu, select **"Plans"**;
2.  Click **"Add a plan"** in the upper right corner;
3.  Fill in the form ([learn more about plans](/guide/plans/overview)); and
4.  Click **"Add plan"** to save.

## 3. Create a customer[](#3-create-a-customer "Direct link to heading")

To create a customer through the user interface:

1.  In the side menu, select **"Customers"**;
2.  Click **"Add a customer"** in the upper right corner;
3.  Fill in the form in the pop-up window
    ([learn more about customers](/guide/customers/customer-management)); and
4.  Click **"Add customer"** to save.

You can also create customers through the API, as described in the
[documentation](/api-reference/customers/create).

## 4. Start a subscription[](#4-start-a-subscription "Direct link to heading")

To start a subscription, you need to assign a plan to an existing customer. To
do so through the user interface:

1.  In the side menu, select **"Customers"**;
2.  Select a customer from the list;
3.  On the right-hand side, click **"Add a plan"**;
4.  Select the plan you would like to assign to your customer; and
5.  Click **"Add plan"** to confirm.

A success toast will be displayed and the new subscription will appear in the
customer view.

You can also start a subscription through the API, as described in the
[documentation](/api-reference/subscriptions/assign-plan).

## 5. Send usage-based events[](#5-send-usage-based-events "Direct link to heading")

Events sent from your backend to Lago will be automatically aggregated according
to the predefined billable metrics. To start sending usage-based events, please
refer to the [documentation](/guide/events/ingesting-usage).

## 6. Invoice your customers[](#6-invoice-your-customers "Direct link to heading")

At the end of the billing period, Lago will automatically generate an invoice
for each customer. Invoices will be sent to your application using webhooks. To
define the URL to which the webhooks will be sent:

1.  In the side menu of the user interface, select **"Developers"**;
2.  On the right-hand side, click **"Add a webhook"**;
3.  Enter the URL of your application; and
4.  Click **"Add webhook"** to confirm.

To learn more about webhooks and invoices, please refer to the
[API documentation](/api-reference/invoices/invoice-object).


# Welcome to Lago

Lago is an open-source software for metering and usage-based billing. It's the best alternative to Chargebee, Recurly or Stripe Billing for companies that need to handle complex billing logic.

This library will allow you to build an entire billing system from scratch. Lago is a real-time, event-based solution made for usage-based billing, subscription-based billing, and all the nuances of pricing in between.

You can use the [self-hosted version](/guide/self-hosted/docker) to deploy Lago on your existing infrastructure or [request access to Lago Cloud](http://getlago.com/book-a-demo) to start using our solution immediately.

## Five-step billing workflow[](#five-step-billing-workflow "Direct link to heading")

### 1. Usage ingestion[](#1-event-ingestion "Direct link to heading")

[Events](/guide/events/ingesting-usage) provide information about your customers'
consumption, with the highest level of granularity. Any product feature for
which you want to charge your customers should correspond to a specific event.
An event can be triggered by an action or can be sent periodically. Lago is able
to ingest events at scale while preventing duplicates.

### 2. Metrics aggregation[](#2-metrics-aggregation "Direct link to heading")

The aggregation process consists in converting events into
[billable metrics](/guide/billable-metrics/create-billable-metrics). There are 4 aggregation types:

| Aggregation    | Description                                                                                            | Type                 |
| -------------- | ------------------------------------------------------------------------------------------------------ | -------------------- |
| `COUNT`        | Counts the number of times an incoming event occurs                                                    | Metered              |
| `COUNT_UNIQUE` | Returns the number of unique values of a predefined property for incoming events                       | Metered or Recurring |
| `LATEST`       | Returns the lastest value of a predefined property for incoming events                                 | Metered              |
| `MAX`          | Returns the maximum value of a predefined property for incoming events                                 | Metered              |
| `SUM`          | Calculates the sum of a predefined property for incoming events                                        | Metered or Recurring |
| `WEIGHTED SUM` | Calculates the sum of a predefined property for incoming events prorated based on time used per period | Metered or Recurring |

### 3. Pricing and packaging[](#3-pricing "Direct link to heading")

Creating [plans](/guide/plans/overview) allows you to define how much your customers
should pay for using your product. You can then combine plans and billable
metrics to implement any billing model (i.e. subscription-based, usage-based, or
hybrid). Billable metrics may be priced differently depending on the associated
plan.

### 4. Invoicing[](#4-invoicing "Direct link to heading")

Lago automatically generates [invoices](/guide/invoicing/overview) for each customer
according to the plan model: the subscription fee can be billed at the beginning
or at the end of the billing period while usage-based charges are always
calculated at the end of the billing period. Invoices include fees, taxes and
customer information.

### 5. Payments[](#5-payments "Direct link to heading")

When an invoice is emitted and finalized, it's ready for payment collection.
Connect payment providers through [native integrations](/guide/payments/overview) or
trigger payments on any PSPs using the invoice payload created by Lago.


# Why billing is a nightmare



<Info>
  The original version of this article is available on [our
  blog](https://www.getlago.com/blog/why-billing-systems-are-a-nightmare-for-engineers).
</Info>

> *"On my first day, I was told: 'Payment will come later, shouldn't be hard
> right?'*
>
> *I was worried. We were not selling and delivering goods, but SSDs and CPU
> cores, petabytes and milliseconds, space and time. Instantly, via API.
> Fungible, at the smallest unit. On all continents. That was the vision.*
>
> *After a week, I felt like I was the only one really concerned about the long
> road ahead. In ambitious enterprise projects, complexity compounds quickly:
> multi-tenancy, multi-users, multi-roles, multi-currency, multi-tax codes,
> multi-everything. These systems were no fun, some were ancient, and often
> 'spaghetti-like'.*
>
> *What should have been a one-year R\&D project ended up taking seven years of
> my professional life, in which I grew the billing team from 0 to 12 people. So
> yes, if you ask me, billing is hard. Harder than you think. It's time to solve
> that once and for all."*
>
> Kevin Deldycke, former VP Engineering at Scaleway

This is a typical conversation we have with engineers on a daily basis.

After my last post about my
['pricing hack'](https://www.getlago.com/blog/pricing-my-only-growth-hack-at-qonto),
some of you asked me why billing was that complex. My co-founder Raffi took up
the challenge of explaining why it's still an unsolved problem for engineers.

We also gathered insights from other friends who went through the same painful
journey, including Algolia, Segment, Pleo... don't miss them! Passing the mic to
Raffi.

When you're thinking about automating billing, this means your company is
getting traction. That's good news!

You might then wonder: should we build it in-house? It does not look complex,
and the logic seems specific to your business. Also, you might want to preserve
your precious margins and therefore avoid existing billing solutions like Stripe
Billing or Chargebee, that take a cut of your revenue. Honestly, who likes this
'rent-seeker' approach?

Our team at Lago still has some painful memories of Qonto's internal billing
system, that we had to build and maintain. Why was it so painful? In this
article, I will provide a high-level view of the technical challenges we faced
while implementing hybrid pricing (based on subscription and usage) and what we
learned during this journey.

![How engineers feel about building a billing system](https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/billing-nightmare-3c8b70de58b169f0a4f882549c9edcb7.png)

## TL;DR: Billing is just 100x harder than you will ever think[](#tldr-billing-is-just-100x-harder-than-you-will-ever-think "Direct link to heading")

"Let's bill yearly as well, should be pretty straightforward" claims the Revenue
team. Great! Everyone is excited to start working on it. Everyone, except the
Tech team. When you start building your internal billing system, it's hard to
think of all the complexity that will pop up down the road, unless you've
experienced it before.

It's common to start a business with a simple pricing. You define one or two
price plans and limit this pricing to a defined number of features. However,
when the company is growing, your pricing gets more and more complex, just like
your entire codebase.

At Qonto, our first users could only onboard on a €9 plan. We quickly decided to
add plans, and 'pay-as-you-go' features (e.g. ATM withdrawals, foreign currency
payments, capital deposit, etc.) to grow revenue.

Also, as Qonto is a neobank, we wanted to charge our customers' wallets
directly, through a ledger connected to our internal billing system. The team
started from a duo of full-time engineers building a billing system (which is
already a considerable investment) to a dedicated cross-functional Pricing team.

This is not specific to Qonto of course. Pleo, another fintech unicorn from
Denmark faced similar issues:

> *"I've learned to appreciate that billing systems are hard to build, hard to
> design, and hard to get working for you if you deviate from 'the standard'
> even by a tiny bit."*
>
> Arnon Shimoni, Product Billing Infrastructure Lead at Pleo

This is not even specific to fintechs. The Algolia team ended up creating a
whole pricing department, now led by Djay, a pricing and monetization veteran
from Twilio, VMWare, Service Now. They switched to a 'pay-as-you-go' pricing
model based on the number of monthly API searches.

> *"It looks easy on paper — however, it's a challenge to bring automation and
> transparency to a customer, so they can easily understand. There is a lot of
> behind-the-scenes work that goes into this, and it takes a lot of engineering
> and investment to do it the right way."*
>
> Bernardette Nixon, CEO at Venture Beat

## Dates[](#dates "Direct link to heading")

When implementing a billing system, dealing with dates is often the number 1
complexity. Somehow, all your subscriptions and charges are based on a number of
days. Whether you make your customers pay weekly, monthly or yearly, you need to
define the billing period.

Here is a non-exhaustive list of difficulties for engineers:

1.  How to deal with leap years?
2.  Do your subscriptions start at the beginning of the month or at the creation
    date of the customer?
3.  How many days/months of trial do you offer?
4.  Who decided February only holds 28 days?
5.  Wait, point 1 is also important for February...
6.  How to calculate usage-based charges (price per second, hour, day)?
7.  Do I resume the consumption or do I stack it month over month? Year over
    year?
8.  Do I apply a pro-rata based on the number of days consumed by my customer?

Although every decision is reversible, billing cycle questions are often the
most important source of customer support tickets, and iterating on them is
quite complex. For instance, Qonto switched from 'anniversary' dates to calendar
dates for its billing periods (see
[here](https://medium.com/qonto-way/biller-migration-how-we-changed-our-billing-cycle-cf3c4cdd7cf4)).
This change was not trivial.

## Upgrades & Downgrades[](#upgrades--downgrades "Direct link to heading")

You need to allow your customers to upgrade or downgrade their subscriptions.
Moving from plan A to plan B seems pretty easy, but it's not. Let's zoom on
potential edge cases.

What should we do when the user:

1.  Upgrades or downgrades in the middle of a period;
2.  Has paid for the original plan in advance;
3.  Needs to pay for the original plan in arrears;
4.  Downgrades from a yearly plan to a monthly plan;
5.  Upgrades from a monthly plan to a yearly plan;
6.  Upgrades or downgrades from a plan paid in advance to a plan paid in arrears
    (and vice-versa); or
7.  Has a discount and upgrades/downgrades?

We did not have a free trial period at the time at Qonto, but Arnon from Pleo
describes this situation
[here](https://arnon.dk/5-things-i-learned-developing-billing-system/).

## Usage-based computations[](#usage-based-computations "Direct link to heading")

Subscription-based billing is the first step when implementing a billing system.
Each customer needs to be affiliated to a plan in order to start charging the
right amount at the right time.

But for a growing number of companies, like Qonto, other charges come alongside
this subscription. These charges are based on what customers really consume.
This is what we call 'usage-based billing'. Most companies end up having a
hybrid pricing model: a monthly subscription fee and 'add-ons' or
'pay-as-you-go' charges on top of it.

These consumption-based charges are tough to track at scale, because they often
come with calculation rules performed on a high volume of events.

Here are some examples:

Segment's pricing is based on the number of monthly tracked users. This means
that they need to count the distinct number of users each month and reset this
value to zero for the next billing period. In order to retrieve the number of
unique visitors, they need to apply a 'distinct' function to deduplicate them.

![Event related to tracked users](https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/introduction/images/tracked-users-event-f81fc6d343efffad1c4b3355517d90db.png)

![Event aggregation for tracked users](https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/introduction/images/tracked-users-aggregation-1c662afae3af55c1d1b43793d0f56cc8.png)

Algolia tracks the number of API searches per month. This means they need to sum
the number of monthly searches for each customer and reset this value to zero
for the next billing period.

![Event related to API searches](https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/introduction/images/api-search-event-9e90f7f9c063238a4e14cfd03d314a1e.png)

![Event aggregation for API searches](https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/introduction/images/api-search-aggregation-23924f13dd3da2e5d73388afffe7e89a.png)

It becomes even more complex when you start calculating charges based on a
timeframe. For instance, Snowflake charges for the compute usage of a data
warehouse per second. This means that they sum the number of gigabytes or
terabytes consumed, multiplied by the number of seconds of compute time.

Consider the example of a utility company that charges \$10 per kilowatt of
electricity per hour. The illustration below shows what needs to be modeled and
automated by the billing system.

![Power consumption diagram](https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/introduction/images/power-consumption-aba79c1bc4259e79144011519a519586.png)

*   **Hour 1**: 10 KW used for 0.5 hour = 5 KW (10 x 0.5)
*   **Hour 2**: 20 KW used for 1 hour = 20 KW (20 x 1)
*   **Hour 3**: 0 KW used for 1 hour = 0 KW (0 x 1)
*   **Hour 4**: 30 KW used for 0.5 hour = 15 KW (30 x 0.5)
*   **TOTAL** = 40 KW used x $10 ⇒ $40

## Idempotency done right[](#idempotency-done-right "Direct link to heading")

Billing errors sometimes occur. Charging a user twice for the same product is
obviously bad for the customer experience, but failing to charge when needed
hurts revenue. That's partly why Finance and BI teams spend so much time on
revenue recognition.

For 'pay-as-you-go' companies, the billing system will process a high volume of
events. When an event needs to be replayed, it needs to happen without billing
the user again. Engineers call it 'idempotency', which means the **ability to
apply the same operation multiple times without changing the result beyond the
first try**.

It's a simple design principle, however, maintaining it at all times is hard.

## The case for a Cash Collection Officer[](#the-case-for-a-cash-collection-officer "Direct link to heading")

Cash collection is the process of collecting the money that customers owe you.
The pet peeve of cash collection is dunning: when payments fail, the merchant
needs to persist and make repeated payment requests to their customers, while
trying not to damage the relationship.

At Qonto, we called these 'waiting funds'. A client's status was 'waiting funds'
when they successfully went through the sign-up, KYC and KYB process but their
account balance was still 0.

For a neobank, the impact is twofold: you can't charge your service fees (e.g.
monthly subscription) and your customer does not generate interchange revenues
(e.g. when you make a payment of $100 with your card, the card issuer earns
$0.5-\$1 of interchange revenue through the merchant's fees).

Therefore, your two main revenue streams are 'null' but you did pay to acquire,
onboard, KYC the user and then to produce and send them a card. We often
half-joked about the need to hire a 'chief waiting funds officer': the financial
impact of this is just as high as the problem is underestimated.

All companies face dunning challenges. For engineers, on top of the billing
architecture, this means that they need to design and build:

1.  A **'retry logic'** to ask for a new payment intent;
2.  An **invoice reconciliation system** (e.g. if several months of charges are
    recovered);
3.  An **app logic to disable access** to the service; and
4.  An **emailing workflow** to urge a user to proceed to the payment.

Some SaaS are even on a mission to fight dunnings and have built full-fledged
companies around cash collection, such as Upflow, which is used by successful
B2B scale-ups, including Front and Lattice.

> *"Sending quality and personalized reminders took us a lot of time and, as
> Lattice was growing fast, it was essential for us to scale our cash collection
> processes. We use Upflow to personalize how we ask our customers for money,
> repeatedly, while keeping a good relationship. We now collect 99% of our
> invoices, effortlessly."*
>
> Jason Lopez, Controller at Lattice

## The labyrinth of taxes and VAT[](#the-labyrinth-of-taxes-and-vat "Direct link to heading")

Taxes are challenging and depend on multiple dimensions. Taxes depend on what
you are selling, your home country and your customer's home country. In the
simplest situations, your tax decision tree should look like this:

![Decision tree for taxes](https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/introduction/images/taxes-vat-46fc3b96167c21bc33b279431aa187ca.png)

Now, imagine that you sell different types of goods/services to different types
of customers in 100+ countries. If you think the logic on paper looks complex,
the engineering challenge is tenfold. Engineers need to think of an entire tax
logic within the application. This pyramidal logic is based on customers and
products, including:

1.  **Taxes at company level**: your company will have a general tax rate that
    applies to all customers by default;
2.  **Taxes at customer level**: the default tax rate can be overridden for each
    customer, depending on the dimensions mentioned above (see illustration); and
3.  **Taxes at feature level**: this is mostly the case for the banking industry.
    At Qonto for instance, banking fees are not subject to taxes but a 20% VAT
    rate applies to non-banking features.

With billing, the devil's in the detail, which is why I always cringe when I see
engineering teams build a home-made system, just because they think "it's not
that complex".

If you've already tackled the topics listed above and think it's a good
investment of your engineering time, go ahead and build it in-house, but make
sure to budget for the maintenance work that is always needed. Another option is
to rely on existing billing platforms, built by specialized teams.

To solve this problem at scale, we've adopted a radical approach: we're building
an open-source billing API for product-led SaaS. Our API and architecture are
open, so that you can embed, fork and customize them as much as your pricing and
internal processes require.

If you're interested, you can [get started](https://www.getlago.com/get-started)
here or [book a demo](http://getlago.com/book-a-demo).


# Download invoices



When a new invoice is `finalized`, Lago will automatically send a
[webhook](/api-reference/webhooks/messages) to notify you. It will also generate a PDF
file that you can download and send to your customer.

<Tabs>
  <Tab title="Dashboard">
    To download an invoice through the user interface:

    1.  Click **"Customers"** in the side menu;
    2.  Select a customer from the list;
    3.  Open the **"Invoices"** tab;
    4.  Click the **ellipsis icon** on the right of the invoice; and
    5.  Click **"Download invoice"** to open the file in a new tab.
  </Tab>

  <Tab title="API">
    You can also download invoices via API ([learn more](/api-reference/invoices/download)).

    <CodeGroup>
      ```bash Download an invoice PDF
      LAGO_URL="https://api.getlago.com"
      INVOICE_ID="__YOU_INVOICE_ID__"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/invoices/$INVOICE_ID/download" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## How to modify the invoice template[](#how-to-modify-the-invoice-template "Direct link to heading")

<Info>
  Changes to the invoice template and new information about your organization do not affect existing invoices and only apply to future invoices.
</Info>

### Add information about your organization

You can modify some of the elements that are included in the PDF invoice, such as information about the organization, its logo and the footer.

To update your organization's information and logo:

1.  Click **"Settings"** in the side menu;
2.  In the **"Organization"** tab, click **"Edit"** in the **"Information"** block;
3.  Choose a file to update the logo and fill out the form to update your organization's information; and
4.  Click **"Save information"** to confirm.

<Info>
  For the logo, you can upload a JPG or PNG file with a maximum size of 800 KB.
</Info>

### Add a custom footer

<Tabs>
  <Tab title="Dashboard">
    To update the footer of the invoice:

    1.  Click **"Settings"** in the side menu;
    2.  Open the **"Invoice"** tab;
    3.  Select **"Edit"** in the **"Invoice default footer"** block;
    4.  Enter your text (maximum 600 characters); and
    5.  Click **"Save information"** to confirm.

    <Frame caption="Adding a custom footer via the user interface">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/custom-footer-3938263609cbf988b298c69afa2812e6.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    You can update the customer footer of invoices by changing the `invoice_footer` in the `billing_configuration` object of your organization endpoint.

    <CodeGroup>
      ```bash Update the customer footer of your invoices
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request PUT "$LAGO_URL/api/v1/organizations" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "organization": {
            "name": "Name1",
            "webhook_url": "https://test-example.example",
            "country": "CZ",
            "address_line1": "address1",
            "address_line2": null,
            "state": "state1",
            "zipcode": "10000",
            "email": "org@email.com",
            "city": "city125",
            "legal_name": null,
            "legal_number": null,
            "tax_identification_number": "EU123456789",
            "timezone": "Europe/Paris",
            "email_settings": [
              "invoice.finalized",
              "credit_note.created"
            ],
            "billing_configuration": {
              "invoice_footer": "footer custom",
              "invoice_grace_period": 3,
              "document_locale": "fr",
            }
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Translate invoices

<Tabs>
  <Tab title="Dashboard">
    To set the default language for documents:

    1.  Click **"Settings"** in the side menu;
    2.  Open the **"Invoice"** tab;
    3.  Select **"Edit"** in the **"Document language"** block;
    4.  Select your preferred language from the list; and
    5.  Click **"Edit language"** to confirm.

    The organization's default language can be overwritten by the customer's preferred language ([learn more](/guide/customers/invoice-customer#preferred-language)).
  </Tab>

  <Tab title="API">
    You can update the customer footer of invoices by changing the `document_locale` in the `billing_configuration` object of your organization endpoint.

    <CodeGroup>
      ```bash Update the documents locale
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request PUT "$LAGO_URL/api/v1/organizations" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "organization": {
            "name": "Name1",
            "webhook_url": "https://test-example.example",
            "country": "CZ",
            "address_line1": "address1",
            "address_line2": null,
            "state": "state1",
            "zipcode": "10000",
            "email": "org@email.com",
            "city": "city125",
            "legal_name": null,
            "legal_number": null,
            "tax_identification_number": "EU123456789",
            "timezone": "Europe/Paris",
            "email_settings": [
              "invoice.finalized",
              "credit_note.created"
            ],
            "billing_configuration": {
              "invoice_footer": "footer custom",
              "invoice_grace_period": 3,
              "document_locale": "fr"
            }
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

Please refer to the API documentation to see the [list of supported languages](/api-reference/resources/locales).


# Export invoices

Lago enables you to filter invoices and export them as a simple or advanced CSV file, tailored to your needs.

## Invoice filtering options

With Lago, filtering your invoice list is straightforward and customizable. To filter invoices effectively, follow these steps:

1.  Go to the **Invoices** section;
2.  **Use quick filters** for fast, predefined filtering;
3.  Select the **Filters options** for more advanced filtering criteria; and
4.  Click **Reset filters** to remove all active filters when needed.

<Frame caption="Invoices filtering options">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/filters-and-quick-filters.png" />
</Frame>

Here is the list of filter options you will encounter in Lago:

*   **Currency:** Filter invoices based on the currency in which they are issued;
*   **Customer:** Filter by the customer associated with the invoices;
*   **Disputed:** Filter invoices to show only those that are disputed or undisputed;
*   **Issuing Dates:** Filter invoices by their issuing dates;
*   **Overdue:** Filter to display only overdue invoices;
*   **Payment Status:** Filter invoices by their payment status;
*   **Status:** Filter invoices by their status; and
*   **Type:** Filter invoices by their type.

## Basic invoices export

The first option is a basic invoice export. This process generates a CSV file containing one row per invoice, based on the filters you have previously applied.
The exported CSV includes relevant invoice details and is sent to the email address of the user who requested the export.
The download link for the CSV file remains valid for 7 days.

<Frame caption="Basic invoices export in CSV">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/invoices-export.png" />
</Frame>

## Detailed invoice fees export

The second option is an advanced invoice export. This process generates a CSV file containing one row per fee (line item of your invoices),
based on the filters you have previously applied. The exported CSV includes detailed information on each fee and line item of your invoices, and is
sent to the email address of the user who requested the export. The download link for the CSV file is valid for 7 days.

<Frame caption="Advanced invoice fees export in CSV">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/fees-export.png" />
</Frame>


# Fees

A fee is a line item in an invoice.

There are few types of fees:

*   **Subscription fees** that correspond to the base amount of the plan;
*   **Charge fees** that correspond to usage-based charges (i.e. the costs
    associated with each billable metric), this fee can be linked to a true-up fee;
*   **Add-on fees** that correspond to a line item appearing in a one off invoice; and
*   **Credit** that correspond to line item appearing in credit notes.

Information about fees includes (but is not limited to):

*   Type;
*   Amount;
*   Currency; and
*   Taxes.

The fee object is embedded within an invoice or credit note object, making it retrievable on its own.
This is illustrated below.:

```json
{
  "fee": {
    "lago_id": "e7e0ee24-7ef3-4b19-8bbf-fb0e75f5c79b",
    "lago_group_id": null,
    "lago_invoice_id": "ffbafe19-2b8d-4376-9510-314566b90724",
    "lago_true_up_fee_id": null,
    "lago_true_up_parent_fee_id": null,
    "item": {
      "type": "add_on",
      "code": "test",
      "name": "Test ",
      "lago_item_id": "1e8d90cb-e305-438b-86b5-a566e97209d0",
      "item_type": "AddOn"
    },
    "pay_in_advance": false,
    "invoiceable": true,
    "amount_cents": 10000,
    "amount_currency": "USD",
    "taxes_amount_cents": 3000,
    "taxes_rate": 30.0,
    "total_amount_cents": 13000,
    "total_amount_currency": "USD",
    "units": "1.0",
    "description": "",
    "unit_amount_cents": 10000,
    "events_count": null,
    "payment_status": "pending",
    "created_at": "2023-07-06T21:01:41Z",
    "succeeded_at": null,
    "failed_at": null,
    "refunded_at": null,
    "vat_amount_cents": 3000,
    "vat_amount_currency": "USD",
    "applied_taxes": [
      {
        "lago_id": "3bdac336-af27-4be4-a4a5-58433f401708",
        "lago_fee_id": "e7e0ee24-7ef3-4b19-8bbf-fb0e75f5c79b",
        "lago_tax_id": "38325421-2145-4b79-bff1-d38a702afe3a",
        "tax_name": "TVA",
        "tax_code": "french_standard_vat",
        "tax_rate": 20.0,
        "tax_description": "French standard VAT",
        "amount_cents": 2000,
        "amount_currency": "USD",
        "created_at": "2023-07-06T21:01:41Z"
      }
    ]
  }
}
```

## Update fee payment status

<Info>
  The `payment_status` of a fee can only be configured if `lago_invoice_id` is
  `null`.
</Info>

This option allows you to define the payment status of a fee yourself. The available options are: `pending`, `succeeded`, `failed`, and `refunded`.

Note that `payment_status` is used to group fees with a `succeeded` status into a specific invoice if `regroup_paid_fee` is set to `invoice`. Outside of this process, the `payment_status` is for your internal use.

## Delete a fee

<Info>
  The deletion of a fee can only be doable if `lago_invoice_id` is `null`.
</Info>

This option allows you to delete a fee that is not linked to any invoice. Please refer to charge [invoiceable or not](/guide/plans/charges/invoiceable-vs-noninvoiceable) for more details.


# Grace period



<Info>
  **PREMIUM FEATURE** ✨

  This feature is only available to users with a premium license. Please
  **[contact us](mailto:hello@getlago.com)** to get access to Lago Cloud and Lago
  Self-Hosted Premium.
</Info>

A grace period is defined as a number days during which invoices remain in
`draft` status, allowing you to review them and make changes before they are
`finalized` and sent for payment collection.

In the example below, the timeline includes a billing period of one month and a
grace period of three days.

<Frame caption="Illustration of the grace period">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/grace-period-timeline-299de2425036f803f20825e8a42ab401.png" />
</Frame>

## Define a grace period at organization level[](#define-a-grace-period-at-organization-level "Direct link to heading")

The organization's grace period applies to all customers by default.

<Tabs>
  <Tab title="Dashboard">
    To define a grace period at organization level through the user interface:

    1.  Access the **"Settings"** section via the side menu;
    2.  Open the **"Invoice"** tab;
    3.  Click **"Edit"** in the **"Grace period"** section;
    4.  Enter the number of days associated with the grace period; and
    5.  Click **"Edit grace period"** to confirm.

    <Frame caption="Grace period in the settings of the app">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/grace-period-organization-eabdac12832b76fd4d75c1a266244339.png" />
    </Frame>

    <Warning>
      If you shorten the organization's grace period, some invoices in `draft`
      status may be automatically `finalized`. For instance, if the initial grace
      period was five days, but then three days into the grace period you decide to
      reduce it to two days, then all `draft` invoices will automatically switch to
      `finalized`.
    </Warning>
  </Tab>

  <Tab title="API">
    You can also modify the organization's grace period at any time through [the API](/api-reference/organizations/update).
    Define a grace period in days by using the `invoice_grace_period` argument in the `billing_configuration` object at an organization level.

    <CodeGroup>
      ```bash Add a grace period on the organization {28}
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request PUT "$LAGO_URL/api/v1/organizations" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "organization": {
            "name": "Name1",
            "webhook_url": "https://test-example.example",
            "country": "CZ",
            "address_line1": "address1",
            "address_line2": null,
            "state": "state1",
            "zipcode": "10000",
            "email": "org@email.com",
            "city": "city125",
            "legal_name": null,
            "legal_number": null,
            "tax_identification_number": "EU123456789",
            "timezone": "Europe/Paris",
            "email_settings": [
              "invoice.finalized",
              "credit_note.created"
            ],
            "billing_configuration": {
              "invoice_footer": "footer custom",
              "invoice_grace_period": 3,
              "document_locale": "fr",
              "vat_rate": 15.0
            }
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Define a grace period at customer level[](#define-a-grace-period-at-customer-level "Direct link to heading")

<Tabs>
  <Tab title="Dashboard">
    To define a grace period at customer level through the user interface:

    1.  Access the **"Customers"** section via the side menu;
    2.  Select a customer from the list;
    3.  Open the **"Settings"** tab of the customer view;
    4.  Click **"Add grace period"** in the **"Grace period"** section;
    5.  Enter the number of days associated with the grace period; and
    6.  Click **"Add grace period"** to confirm.

    <Frame caption="Grace period in the customer view">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/grace-period-customer.png" />
    </Frame>

    <Warning>
      If you shorten the customer's grace period, some invoices in `draft` status
      may be automatically `finalized`. For instance, if the initial grace period
      was five days, but then three days into the grace period you decide to reduce
      it to two days, then all `draft` invoices will automatically switch to
      `finalized`.
    </Warning>
  </Tab>

  <Tab title="API">
    You can also modify the customer's grace period at any time through the user interface or [the API](/api-reference/customers/create).
    Define a grace period in days by using the `invoice_grace_period` argument in the `billing_configuration` object at a customer level.

    <CodeGroup>
      ```bash Add a grace period on the customer {28}
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/customers" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "customer": {
            "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
            "address_line1": "5230 Penfield Ave",
            "address_line2": "",
            "city": "Woodland Hills",
            "country": "US",
            "currency": "EUR",
            "email": "dinesh@piedpiper.test",
            "legal_name": "Coleman-Blair",
            "legal_number": "49-008-2965",
            "tax_identification_number": "EU123456789",
            "logo_url": "http://hooli.com/logo.png",
            "name": "Gavin Belson",
            "phone": "1-171-883-3711 x245",
            "state": "CA",
            "timezone": "Europe/Paris",
            "url": "http://hooli.com",
            "zipcode": "91364",
            "tax_codes": []
            "billing_configuration": {
              "invoice_grace_period": 3,
              "payment_provider": "stripe",
              "provider_customer_id": "cus_12345",
              "sync": true,
              "sync_with_provider": true,
              "document_locale": "fr",
            },
            "metadata": [
              {
                "key": "Name",
                "value": "John",
                "display_in_invoice": true
              }
            ]
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

The customer's grace period overrides the organization's grace period. It only
applies to the customer with whom it is associated.

## Application scope and possible actions[](#application-scope-and-possible-actions "Direct link to heading")

The grace period applies to **subscription invoices**. It does not apply to
invoices related to add-ons or credit purchases.

The creation of a `draft` invoice triggers the `invoice.drafted`
[webhook](/api-reference/webhooks/messages).

When a subscription invoice is in `draft` status, you can:

*   **Add usage records** by sending events with a `timestamp` within the relevant
    billing period;
*   **Edit a specific fee** by adjusting the total amount or the total units;
*   **Apply coupons** to the customer's account; and
*   **Add credits** to the customer's wallet and credit note wallet.

### Edit a specific fee

To edit a specific fee, follow these steps in the Dashboard:

1.  Open a draft invoice's details page;
2.  Click the 'three dots' icon next to the desired fee;
3.  Change the invoice's display name if needed; and/or
4.  Select either `Total amount` or `Total unit` for adjustment;
5.  For `Total amount`, enter units and unit amount. Note: This will overwrite existing fee details.
6.  For `Total unit`, input new units. Lago will then automatically recalculate the fee based on the charge model.

This action is exclusive to the Dashboard.

### Add usage records

In order to add usage to an invoice that is in `draft` status, the `timestamp`
of the [events](/guide/events/ingesting-usage) must be
within the billing period. Consider the following example:

> The billing period started on January 1st and ended on January 31st. We have
> defined a 3-day grace period and today is February 2nd.
>
> On February 1st, Lago automatically generated a `draft` invoice for the period
> January 1st to January 31st.
>
> We want to send additional usage records for this invoice. To do so, the
> timestamp of our events must be included in the period January 1st to January
> 31st.
>
> `1673457300` (i.e. January 11th, 2023) is a valid timestamp, therefore the
> event will be included in the `draft` invoice.
>
> However, `1675354500` (i.e. February 2nd, 2023) is outside the billing period
> under consideration, therefore the event will not be included in the `draft`
> invoice, it will be included in the next invoice.

After sending events, you can **go to the invoice list and refresh** the
corresponding `draft` invoice to ensure your new events have been taken into
account.

When all changes have been made, you can either wait for the grace period to
expire (the invoice status will automatically switch to `finalized`) or you can
**finalize the invoice manually** through the user interface or the API.

When an invoice is `finalized`, it can no longer be edited. Finalizing an
invoice triggers the `invoice.created` webhook.

<Frame caption="Draft invoice in the Lago app">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/grace-period-draft-invoice-0a9ccbd1d7dc1b87faeb5a44abf484e1.png" />
</Frame>

<Info>
  Coupons and credits that are applied/added during the grace period will not
  appear on `draft` invoices but will be automatically deducted from the
  customer's next `finalized` invoice.
</Info>


# Invoice metadata



## Add metadata on invoice

Adding metadata to an `invoice` object can provide additional structured information and context. For example, after finalizing the invoice, you can define a key-value pair in the `invoice` object to store your local invoice ID from your government invoicing system. To do so:

1.  Navigate to the Invoice detail page to target a specific invoice;
2.  Click on "Add metadata";
3.  Add the information (kindly note, a key cannot exist without its corresponding value, and vice versa); and
4.  Save to confirm.

<Info>
  The invoice metadata will be included in the `invoice` object but will not be displayed on the PDF file.
</Info>

## Edit metadata on invoice

**To edit metadata from the user interface:**

1.  Navigate to the Invoice detail page to target a specific invoice;
2.  Click on "Edit metadata";
3.  Add, edit, remove information (kindly note, a key cannot exist without its corresponding value, and vice versa); and
4.  Save to confirm.

**To edit metadata using the API:**

1.  In your payload, locate the key-value pair with the metadata ID you want to edit; and
2.  Modify the key and/or value as needed.

<Tip>
  When editing invoice metadata through the API, please make sure to include the existing metadata in your payload to avoid removing it.
</Tip>

## Delete metadata on invoice

**To delete a metadata key-value pair from the user interface:**

1.  Navigate to the Invoice detail page for the specific invoice;
2.  Click on "Edit metadata";
3.  Click on the trash icon next to the metadata you want to remove; and
4.  Save to confirm.

**To delete a metadata key-value pair from the API:**

1.  Do not include the metadata ID you want to delete in your payload.

## Invoice metadata limitations

1.  You can add up to 5 metadata key-value pairs;
2.  Keys must be strings of 20 characters maximum; and
3.  Values must be strings of 255 characters maximum.


# Net payment term



A net payment term refers to the specified number of days within which the end customer is required to settle the invoice after its finalization.
This term not only affects the `payment_due_date` within the invoice payload but also influences the due date mentioned in the downloadable PDF version of the invoice.

To illustrate, consider the following scenario:
a billing cycle spanning one month, accompanied by a net payment term of 15 days.

<Frame caption="Illustration of the net payment term period">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/net-payment-term-timeline.png" />
</Frame>

## Application scope[](#application-scope "Direct link to heading")

The net payment term period applies to all types of invoices.
It does not trigger any webhook when the `payment_due_date` becomes overdue.

The net payment term period applies to all types of invoices and is used to compute the due date. When the `payment_due_date` has passsed, the invoice is flagged as `Overdue`. This action sets the `payment_overdue` field to true, until the payment is `succeeded`, `payment_dispute_lost_at` is applied, or the invoice is voided.

## Define a net payment term at organization level[](#define-a-net-payment-term-at-organization-level "Direct link to heading")

The organization's net payment term applies to all customers by default.

<Tabs>
  <Tab title="Dashboard">
    To define a net payment term at the organization level via the user interface, follow these steps:

    1.  Access the **"Settings"** section using the side menu;
    2.  Navigate to the **"Invoice"** tab;
    3.  Click **"Edit"** in the **"Net payment term"** section;
    4.  Select the desired number of days for the payment term or opt for a custom duration; and
    5.  Confirm by clicking **"Edit net payment term"**.
  </Tab>

  <Tab title="API">
    You can also modify the organization’s net payment term at any time through [the API](/api-reference/organizations/update).
    Define a net payment term in days by using the `net_payment_term` argument within the `organization` object.

    <CodeGroup>
      ```bash Add a net payment term on the organization
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request PUT "$LAGO_URL/api/v1/organizations" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "organization": {
        	    "net_payment_term": 15
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Define a net payment term at customer level[](#define-a-net-payment-term-at-customer-level "Direct link to heading")

<Tabs>
  <Tab title="Dashboard">
    To define a net payment term at the customer level through the user interface, follow these steps:

    1.  Access the **"Customers"** section via the side menu;
    2.  Select a customer from the list;
    3.  Open the **"Settings"** tab of the customer view;
    4.  Click **"Add a net payment term"** in the **"Net payment term"** section;
    5.  Choose the desired number of days for the payment term or opt for a custom duration; and
    6.  Click **"Add net payment term"** to confirm.
  </Tab>

  <Tab title="API">
    You can also modify the customer's net payment term at any time through [the API](/api-reference/customers/update).
    Define a net payment term in days by using the `net_payment_term argument` within the `customer` object.

    <CodeGroup>
      ```bash Add a net payment term on a customer
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request PUT "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "customer": {
        	    "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
        	    "net_payment_term": 15
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

The customer's net payment term supersedes the one defined at the organization level.
It exclusively applies to the associated customer.


# Overview

Lago automatically generates invoices for each customer according to the plan model.

When a new invoice is generated, Lago also sends an `invoice.created` webhook
([learn more](/api-reference/webhooks/messages)).

When an invoice is linked to an add-on, another type of webhook is sent, called
`invoice.add_on_added`.

## Invoice object[](#invoice-object "Direct link to heading")

Invoices include (but are not limited to):

*   Invoice number;
*   Billing period;
*   Customer information;
*   Fees; and
*   Taxes.

You can [download invoices](/guide/invoicing/download-invoices) or use the
[invoice object](/api-reference/invoices/invoice-object) to create your own invoice
template.

<Tip>
  You can also use the invoice object to transmit information to your accounting
  software or payment service provider.
</Tip>

## Invoice numbering[](#invoice-numbering "Direct link to heading")

With Lago, invoice numbering is generated every time an invoice is finalized. You have the flexibility to customize how invoice numbers are incremented to align with your organizational structure and customer management approach.

*   **Invoice numbering per customer**: This setting is designed to increment invoice numbers individually for each customer.
    It ensures that each customer has their own unique sequence of invoice numbers, separate from other customers.
    This approach is ideal for maintaining distinct and isolated numbering patterns for each customer, aiding in clear tracking and accounting processes.
*   **Invoice numbering across the organization**: Opting for this method applies a global sequence for incrementing invoice numbers across your entire organization. Instead of having individual sequences for each customer, all invoices within the organization follow a single, unified numbering system. This creates a continuous and organization-wide sequence for all invoice numbers, simplifying the invoice management process. In that case, invoices are incremented per month (dynamic value used is `YYYYMM`).

## Invoice prefix customization[](#invoice-prefix-customization "Direct link to heading")

Lago also allows you to customize the prefix for documents, including invoices and credit notes.
By default, Lago auto-generates this prefix by combining the first three letters of your organization's name with the last four digits of your organization ID. However, you have the flexibility to fully customize this field to better align with your organization's branding or numbering conventions. This feature ensures clarity and consistency across your documents while allowing you to maintain a professional and personalized appearance in your invoicing system.

## Custom invoice grouping[](#invoice-grouping "Direct link to heading")

Grouping invoice line items in a way that provides clearer insight for your customers can be more beneficial than sticking to the default charge setup in Lago.

For instance, as an AI service provider, you might prefer to regroup all fees associated to one charge by a specific `model` used by a customer, without the need to individually list each model in Lago.

When setting up a charge with a `standard` charge model, you can use `model_name` as an event property in the `grouped_by` attribute. If every event reported to Lago includes a `model_name`, Lago is capable of adjusting your invoice so that charges are organized under the respective model name for that particular charge. Consequently, Lago will also automatically allocate the usage costs for each model.

You can specify multiple `grouped_by` keys for your charge; the order you set them in dictates how they will be displayed on the invoice, affecting the presentation of charges.

<Note>
  The `grouped_by` feature is exclusively available for the `standard` charge model.
</Note>

## Finalize empty invoices

By default, Lago finalizes all invoices, including those with a final amount of zero. However, some customers may prefer to skip empty invoices to avoid unnecessary accounting documents.
In such cases, you **can configure Lago to skip the issuance of invoices when they are empty**.

### Empty invoices definition

Lago considers an invoice empty only if it has no line items before applying coupons or discounts.
If an applicable discount reduces an invoice's total to zero, Lago will not consider this invoice as part of the empty invoices scope and will still finalize it.

### Organization level

The `finalize_zero_amount_invoice` setting is set to `true` by default. At the organization level, you can change this value to `false` at any time.
When set to `false`, empty invoices won't be finalized for any customers unless specifically overridden at the customer level.

<Tabs>
  <Tab title="Dashboard">
    To modify this setting from the Lago user interface:

    1.  Go to Settings in your app;
    2.  Navigate to the Invoices section; and
    3.  Update the value in the **'Finalize zero amount invoice'** section according to your preference.
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Update the organization's settings
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/organizations" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "organization": {
            "country": "US",
            "finalize_zero_amount_invoice": true
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Customer level

By default, new customers inherit the `finalize_zero_amount_invoice` setting from the organization.
You can override this setting for individual customers to meet specific needs.

The available options are:

*   `inherit`: Follows the organization's setting;
*   `skip`: Skips finalizing empty invoices; or
*   `finalize`: Always finalizes invoices, even if empty.

<Tabs>
  <Tab title="Dashboard">
    To modify this customer setting from the Lago user interface:

    1.  Go to a specific customer;
    2.  Navigate to the Settings section; and
    3.  Override the value in the **'Finalize zero amount invoice'** section according to your preference.
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Update the customer's settings
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/customers" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "customer": {
            "external_id": "hooli_12345",
            "address_line1": "100 Fintech Devcon Street",
            "city": "Austin",
            "country": "US",
            "email": "hooli@fintech.com",
            "legal_number": "54321",
            "name": "Hooli 12345",
            "state": "Texas",
            "tax_identification_number": "1234",
            "zipcode": "9399",
            "finalize_zero_amount_invoice": "skip"
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Taxes

When generating invoices, you may need to apply vat or other taxes. By creating taxes and applying them to the organization or/and customers,  their invoices will be directly affected.

## Create taxes[](#create-taxes "Direct link to heading")

**Follow those steps to add a new tax:**

<Tabs>
  <Tab title="Dashboard">
    1.  Access the tax settings page through the **Settings** section > **Taxes** tab;
    2.  In the upper right corner of the list, click **"Add"** to create a new tax;
    3.  Enter its `name`;
    4.  Assign it a unique `code` (i.e. unique ID as defined in your backend system);
    5.  Add a `description` *(optional)*; and
    6.  Define the `rate` that applies.

    <Frame caption="Create a tax in the settings">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/create-tax.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Premium Plan Example
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/taxes" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "tax": {
          "name": "french vat",
          "code": "french_vat",
          "description":"French standard VAT",
          "rate": 20.00,
          "applied_to_organization": false
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Editing and deleting taxes[](#edit-delete-taxes "Direct link to heading")

A tax can be deleted or edited even if it is linked to an organization or a customer.
However, it's important to note that any change made to a tax object, including its removal, has an impact on all existing draft invoices or upcoming invoices associated with this tax.

Available actions include:

*   **Edit**: allows you to modify the name, code and rate of the tax object; and
*   **Delete**: allows you to delete the tax object and remove it from the list (this action cannot be undone).

## Apply taxes to objects

When generating invoices, you may need to apply taxes.
The tax rate applies to all fees (i.e. subscription fees and charges) and appears on the invoices.

### Taxes at the organization level

To apply tax objects to the organization:

<Tabs>
  <Tab title="Dashboard">
    1.  Access the invoice settings page through the **Settings** section > **Invoice** tab;
    2.  In the **Taxes on organization** section, click **"Add"** to add a new tax;
    3.  Select the tax object you want to apply; and
    4.  Repeat the action if you want to add another tax.

    <Frame caption="Add a tax on the organization">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/tax-on-organization.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Premium Plan Example
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request PUT "$LAGO_URL/api/v1/taxes" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "tax": {
          "code": "french_vat",
          "applied_to_organization": true
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Taxes at the customer level

To apply tax objects to a specific customer:

<Tabs>
  <Tab title="Dashboard">
    1.  Access the customer settings page through the **Customer** details page > **Settings** tab;
    2.  In the **Tax rates** section, click **"Add a tax"** to add a new tax;
    3.  Select the tax object you want to apply; and
    4.  Repeat the action if you want to add another tax.

    <Frame caption="Add a tax on the customer">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/tax-on-customer.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Premium Plan Example
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request PUT "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "customer": {
          "code": "acme_inc",
          "tax_codes": ["french_vat"]
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Taxes at the plan and charges level

Follow these steps to apply tax objects to a plan:

<Tabs>
  <Tab title="Dashboard">
    1.  Ensure that you have already created the necessary taxes on your account.
    2.  Navigate to the **Plan** section and click on **Add a plan**.
    3.  In the **Plan settings** section, click on **Add a tax rate**.
    4.  If you have usage-based charges, expand the **More options** section for the charge and click on **Add a tax rate** to define taxes specific to that charge.
    5.  **Note**: If taxes are defined on charges, they will override the tax rate defined at the plan level.
    6.  Complete the process of creating your plan and apply it to customers to generate an invoice.

    <Frame caption="Add a tax on the charge">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/tax-on-charges.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Add taxes to a plan and to charges
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/plans" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "plan": {
          "name": "Starter",
          "code": "starter",
          "interval": "monthly",
          "description": "",
          "amount_cents": 9900,
          "amount_currency": "USD",
          "trial_period": "",
          "pay_in_advance": true,
          "bill_charges_monthly": null,
          "tax_codes": ["french_standard_vat"]
          "charges": [
            {
              "lago_billable_metric_id": "61ddebee-f8ac-4794-90cf-d626b55ab0ed",
              "billable_metric_code": "user_seat",
              "charge_model": "standard",
              "invoiceable": true,
              "pay_in_advance": false,
              "prorated": false,
              "min_amount_cents": 0,
              "tax_codes":["french_standard_vat"]
              "properties": {
                "amount": "0.10"
              }
            }	
          ]
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Taxes at the add-on level

Follow these steps to apply tax objects to a add-on:

<Tabs>
  <Tab title="Dashboard">
    1.  Make sure you have already set up the required taxes within your account.
    2.  Navigate to the "Add-ons" section and click on "Add an add-on."
    3.  Within the "Add-on settings" area, click on "Add a tax rate."
    4.  Finish creating your add-on and apply it to customers using a one-off invoice to generate the invoice.

    <Frame caption="Add a tax on the add-on">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/invoicing/images/tax-on-add-on.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Add taxes to an add-on
      {
        "add_on": {
          "name": "Setup fee",
          "code": "setup_fee",
          "amount_cents": 100000,
          "amount_currency": "USD",
          "description": "",
          "tax_codes": ["french_standard_vat"]
        }
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<br />

<Tip>
  Keep in mind that tax rates defined at the add-on level can be overridden when creating a one-off invoice.
</Tip>

## Tax hierarchy

### Invoice linked to a subscription

When an invoice linked to a subscription is generated,
the taxation process follows a hierarchy that determines how taxes are applied to different fees:

1.  Taxes defined at the **organization** level will impact all invoice fees (subscription & charges).
2.  Taxes defined at the **customer** level will override the organization-level taxes and impact all invoice fees (subscription & charges).
3.  Taxes defined at the **plan** level will override the customer-level taxes and impact all invoice fees (subscription & charges).
4.  Taxes defined at the **charge** level will override the plan-level taxes but will impact only the fee associated with that particular charge.

### Invoice linked to a one-off-invoice

When an invoice linked to a one-off is generated, the taxation process follows a hierarchy that determines how taxes are applied to different fees:

1.  Taxes defined at the **organization** level will impact all invoice fees
2.  Taxes defined at the **customer** level will override the organization-level taxes and impact all invoice fees
3.  Taxes defined at the **add-on** level will override the customer-level taxes and impact only the fee associated with that particular add-on
4.  While creating a one-off invoice, taxes defined at the **fees** level will override add-on-level taxes but will solely impact the fee associated with that particular add-on.

### Invoice linked to prepaid credit

Since we treat the purchase of credits as an upfront payment before usage, invoices generated for prepaid credit purchases will not include any taxes.

## Auto-detect european taxes with Lago

Lago now features an automatic European tax detection integration for your customers.
Check out our easy-to-follow [integration guide](/integrations/taxes/lago-eu-taxes).


# Void invoices



Voiding an invoice is akin to deleting or canceling it in principle.
Yet, voiding preserves a paper trail, enabling you to locate the invoice by its number.
Voided invoices are considered as having zero value for reporting and are not payable.
Importantly, this status is final, meaning the invoice's status remains unalterable.

Once you void an invoice, it remains accessible through the UI views and shows a status `voided` indicating it has been voided.
You can void an invoice only when it's in a `finalized` status, and the payment status is not `succeeded`.

<Tabs>
  <Tab title="Dashboard">
    To void an invoice using the user interface:

    1.  Go to the **"Invoices"** list;
    2.  Click the **ellipsis icon** on the right, on the line corresponding to the invoice;
    3.  Select **"Void invoice"**; and
    4.  Confirm to void the invoice.
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Void an existing invoice
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"
        INVOICE_ID="__YOUR_INVOICE_ID__"

        curl --location --request POST "$LAGO_URL/api/v1/invoices/$INVOICE_ID/void" \
          --header "Authorization: Bearer $API_KEY"

      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Restrictions on voiding invoices

You cannot void an invoice when:

*   The invoice is in `draft` status, as it hasn't been finalized yet; or
*   The payment status of the invoice is `succeeded`, indicating that the payment has been successfully processed; or
*   There is still credit available for one of the credit notes linked to the invoice; or
*   The invoice has already been voided.

## Voiding invoices with applied discounts

*   Coupons applied to an invoice marked as void are lost;
*   Prepaid credits deducted from an invoice marked as void are refunded, provided the wallet is still active; and
*   Credit notes applied to an invoice marked as void are refunded to the credit note wallet.


# Lago Cloud

Lago Cloud is the fully hosted version of our open-source billing API.

With a cloud account:

1.  You don't have to maintain the solution;
2.  You can start building your billing system immediately; and
3.  You benefit from automatic updates.

[Request access to Lago Cloud](http://getlago.com/book-a-demo) to get started.


# Lago OpenAPI



Using our Open API is a great way to explore and interact with Lago's API documentation.

## Prerequisites[](#prerequisites "Direct link to heading")

Before you start using our Open API, here are some important prerequisites and useful links:

1.  Create a free [Postman](https://postman.com) account;
2.  Use the [Swagger](https://swagger.getlago.com/) for Lago's API documentation;
3.  Open a Lago account to get your API key; and
4.  Check out our public [GitHub repository](https://github.com/getlago/lago-openapi).

## Using Lago Open API with Postman[](#using-lago-open-api-with-postman "Direct link to heading")

The Swagger used to document Lago's API can be imported directly into Postman. To do so:

1.  **Copy the following link:** [https://swagger.getlago.com/openapi.yaml](https://swagger.getlago.com/openapi.yaml) (this link can also be found on the Swagger's page);
2.  In Postman, under **Import > Link**, paste the URL above;
3.  Click **Continue**;
4.  Click the **Import** button; and
5.  In the menu, under **API**, find the newly created **Lago API documentation**.

It only takes a few seconds to complete the import. You can then use this API to generate a new collection.

Please don't forget to enter the API key associated with your organization's Lago account to authenticate your API requests.


# Migration to v1.2.0



Dear Lago Community, 👋

We're writing to inform you of upcoming changes in the Lago API that may impact your workflows.

# Why are we doing this?

We understand that change can sometimes be challenging. However, we believe it's essential for growth and improvement.

In our continuous efforts to improve Lago's scalability and flexibility, we are updating our API to streamline the delivery of multiple features. This approach allows us to deliver more value to you and will pave the way for exciting new releases, including:

1.  **Infinite Dimension Structure:** With filters, enjoy unlimited depth in dimension structures, enabling you to merge multiple billable metrics into a single event code;
2.  **High Usage Ingestion System:** Overcome scalability issues with the ability to send over 10,000 events per second;
3.  **Current/Past Usage Performance Improvements:** Experience near-real-time data query with enhanced performance for current and past usage endpoints;
4.  **Alerting Scenarios:** Set up custom alerts for critical events such as unpaid invoices, reaching wallet credit thresholds, and many more;
5.  **Workflow Creation:** Seamlessly trigger actions within Lago based on custom scenarios, like pausing subscriptions or upgrading plans based on alerts; and
6.  **Entitlements Scenarios:** Utilize Lago's aggregated usage data to manage access to product features based on custom rules.

# Timeline

We will maintain the current API logic until **July 9, 2024**. However, after this date, previous versions will no longer be supported. We kindly ask you to update your integration before that day to avoid any potential breaking change.

# What are the changes?

## 1. Transition from `group` to `filters`

We're introducing a new method for building infinite levels of dimensions in Lago with the concept of `filters`.

<Warning>
  Creating or editing billable metrics or plans via the user interface will result in the creation of `filters`.
  Therefore, you may encounter issues if you make changes via the interface but still use `groups` when creating or editing objects via API.
</Warning>

### Impact on billable metrics

*   Introducing `billable_metrics.filters`
*   Deprecating `billable_metrics.group`

**Deprecating "billable\_metrics.group"**
The `group` object is deprecated and will be removed from the `billable_metric` object on July 9, 2024.
Please update all integrations currently using `billable_metrics.group` (see example below).

```diff "billable_metrics.group" with 1 level
{
  "billable_metric": {
    …
-    "group": {
-      "key": "provider",
-      "values": ["AWS", "Google", "Azure"]
-   }
+   "filters": [
+	  {
+	    "key": "provider",
+	    "values": ["AWS", "Google", "Azure"]
+	  }
+	]
  }
}
```

```diff "billable_metrics.group" with 2 levels
{
  "billable_metric": {
    …
-    "group": {
-      "key": "provider",
-      "values": [
-        {
-          "name": "AWS",
-          "key": "region",
-          "values": ["Europe", "Africa", "Asia"]
-        },
-        {
-          "name": "Google",
-          "key": "region",
-          "values": ["Europe", "North America"]
-        },
-        {
-          "name": "Azure",
-          "key": "region",
-          "values": ["North America", "Asia"]
-        }
-      ]
-    }
+    "filters": [
+      {
+        "key": "provider",
+        "values": ["AWS", "Google", "Azure"]
+      },
+      {
+        "key": "region",
+        "values": ["Europe", "Africa", "Asia", "North America"]
+      }
+    ]
  }
}

```

<Warning>
  Note that the billable\_metric object will only display filters and groups if
  applicable.
</Warning>

### Impact on API endpoints

*   Deprecating `List all billable metric groups`.

The endpoint `List all billable metric groups` is deprecated. It will be supported until July 9, 2024 and will then be removed.

```
GET https://api.getlago.com/api/v1/billable_metrics/{code}/groups
```

### Impact on plans

*   Introducing `plans.charges.filters`
*   Deprecating `plans.charges.group_properties`

**Deprecating "billable\_metrics.groups" with one level**
The `group_properties` object is deprecated and will be removed from `plans.charges` on July 9, 2024.

Please update all integrations currently using `plans.charges.group_properties` (see example below).

```diff
{
  "plans": {
    …
    "charges": [
    {
      …
      "properties": {
        "amount": "0",
      },
-      "group_properties": [
-        {
-          "group_id": "__GROUP_ID__",
-          "invoice_display_name": "AWS in Europe",
-          "values": {
-            "amount": "15",
-          }
-        },
-        {
-          "group_id": "__GROUP_ID__",
-          "invoice_display_name": "Google in Europe",
-          "values": {
-            "amount": "20",
-          }
-        }
-      ]
+      "filters": [
+        {
+          "values": {
+            "provider": "AWS",
+            "region": "Europe"
+          },
+          "invoice_display_name": "AWS in Europe"
+          "properties": { "amount": "15" }
+        },
+        {
+          "values": {
+            "provider": "Google",
+            "region": "Europe"
+          },
+          "invoice_display_name": "Google in Europe"
+          "properties": { "amount": "20" }
+        }
+      ]
    }
  }
}
```

<Warning>
  Note that the plan object will only display filters and group\_properties if
  applicable.
</Warning>

### Impact on fees

*   Introducing `fees.lago_charge_filter_id`
*   Deprecating `fees.lago_group_id`

**Deprecating "billable\_metrics.groups" with one level**
The `lago_group_id` field is deprecated and will be removed from `fees` on July 9, 2024.

Please update all integrations currently using `fees.lago_group_id` or `invoice.fees.lago_group_id` (see example below).

```diff
{
  "fees": {
    …
-    "lago_group_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
+    "lago_group_id": null,
+    "lago_charge_filter_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    …
  }
}
```

<Warning>This change also affects the invoice object.</Warning>

### Impact on customer usage

*   Introducing `customer_usage.charges_usage.filters`
*   Deprecating `customer_usage.charges_usage.groups`

**Deprecating "billable\_metrics.groups" with one level**
The `charges_usage.groups` field is deprecated and will be removed from `customer_usage` on July 9, 2024.

Please update all integrations currently using `customer_usage.charges_usage.groups` (see example below).

```diff
{
  "customer_usage": {
    …
    "charges_usage": [
      …
      {
-        "groups": [
-          {
-            "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
-            "key": "null",
-            "value": "europe",
-            "units": "0.9",
-            "amount_cents": 1000,
-            "events_count": 10
-          }
-        ]
+        "filters": [
+          {
+            "values": {
+              "provider": "AWS",
+              "region": "Europe"
+            }
+            "units": "0.9",
+            "amount_cents": 1000,
+            "events_count": 10
+          }
+        ]
      }
    ]
    …
  }
}
```

## 2. Mandatory `external_subscription_id` field in event payloads

To enable real-time functionalities, event payloads must include `external_subscription_id`.
Events that only include `external_customer_id` will not be taken into account when aggregating usage in upcoming versions.

*   Making `events.external_subscription_id` required

**Making "events.external\_subscription\_id" required**
Sending `event.external_subscription_id` will be mandatory starting July 9, 2024.

Please update all integrations currently using `POST /events` (see example below).

```diff
{
  "event": {
    "transaction_id": "__UNIQUE_ID__",
-   "external_customer_id": "__YOUR_CUSTOMER_ID__",
+   "external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
    "code": "__BILLABLE_METRIC_CODE__",
    "timestamp": $(date +%s),
    "properties": {
      "custom_field": 12
    }
  }
}
```

## 3. Deprecated fields

We will remove the following deprecated fields in order to preserve the quality of the API and for clarity.

| Deprecated field                                     | Substitution field                                   |
| ---------------------------------------------------- | ---------------------------------------------------- |
| `applied_coupon.expiration_date`                     | `applied_coupon.expiration_at`                       |
| `billable_metric.group`                              | `billable_metric.filters`                            |
| `coupon.expiration_date`                             | `coupon.expiration_at`                               |
| `credit.before_vat`                                  | `credit.before_taxes`                                |
| `credit.item.lago_id`                                | `credit.item.lago_item_id`                           |
| `credit_note.balance_amount_currency`                | `credit_note.currency`                               |
| `credit_note.credit_amount_currency`                 | `credit_note.currency`                               |
| `credit_note.refund_amount_currency`                 | `credit_note.currency`                               |
| `credit_note.sub_total_vat_excluded_amount_currency` | `credit_note.currency`                               |
| `credit_note.sub_total_vat_excluded_amount_cents`    | `credit_note.sub_total_excluding_taxes_amount_cents` |
| `credit_note.total_amount_currency`                  | `credit_note.currency`                               |
| `credit_note.vat_amount_currency`                    | `credit_note.currency`                               |
| `credit_note.vat_amount_cents`                       | `credit_note.taxes_amount_cents`                     |
| `credit_note.vat_amount_currency`                    | `credit_note.currency`                               |
| `customer.billing_configuration.vat_rate`            | `customer.taxes[].rate`                              |
| `customer_usage.amount_currency`                     | `customer_usage.currency`                            |
| `customer_usage.charge_usages.groups`                | `customer_usage.charge_usages.filters`               |
| `customer_usage.from_date`                           | `customer_usage.from_datetime`                       |
| `customer_usage.to_date`                             | `customer_usage.to_datetime`                         |
| `customer_usage.total_amount_currency`               | `customer_usage.currency`                            |
| `customer_usage.vat_amount_cents`                    | `customer_usage.taxes_amount_cents`                  |
| `customer_usage.vat_amount_currency`                 | `customer_usage.currency`                            |
| `event_error.input_params.code`                      | `event_error.event.code`                             |
| `event_error.input_params.external_customer_id`      | `event_error.event.external_customer_id`             |
| `event_error.input_params.external_subscription_id`  | `event_error.event.external_subscription_id`         |
| `event_error.input_params.properties`                | `event_error.event.properties`                       |
| `event_error.input_params.timestamp`                 | `event_error.event.timestamp`                        |
| `event_error.input_params.transaction_id`            | `event_error.event.transaction_id`                   |
| `fee.unit_amount_cents`                              | `fee.precise_unit_amount`                            |
| `fee.vat_amount_cents`                               | `fee.taxes_amount_cents`                             |
| `fee.vat_amount_currency`                            | `fee.amount_currency`                                |
| `invoice.amount_currency`                            | `invoice.currency`                                   |
| `invoice.amount_cents`                               | `invoice.fees_amount_cents`                          |
| `invoice.credit_amount_currency`                     | `invoice.currency`                                   |
| `invoice.credit_amount_cents`                        | `invoice.credits[].amount_cents`                     |
| `invoice.fees.group_invoice_display_name`            | `invoice.fees.filter_invoice_display_name`           |
| `invoice.fees.lago_group_id`                         | n/a                                                  |
| `invoice.legacy`                                     | n/a                                                  |
| `invoice.sub_total_vat_excluded_amount_cents`        | `invoice.sub_total_excluding_taxes_amount_cent`s     |
| `invoice.sub_total_vat_included_amount_cents`        | `invoice.sub_total_including_taxes_amount_cent`s     |
| `invoice.total_amount_currency`                      | `invoice.currency`                                   |
| `invoice.vat_amount_cents`                           | `invoice.taxes_amount_cents`                         |
| `invoice.vat_amount_currency`                        | `invoice.currency`                                   |
| `organization.billing_configuration.vat_rate`        | `organization.taxes[].rate`                          |
| `plan.charges.group_properties`                      | `plan.charges.filters`                               |
| `subscription.subscription_date`                     | `subscription.subscription_at`                       |
| `wallet.balance`                                     | `wallet.balance_cents`                               |
| `wallet.expiration_date`                             | `wallet.expiration_at` \`                            |

# Get involved

Your feedback is important to us. If you have any questions, encounter issues, or have suggestions, please reach out to us via the Slack community.

We understand that breaking changes may require you to adapt, so we apologize for any inconvenience caused. Our team is committed to providing support throughout this transition process to minimize disruptions.

Thanks for your understanding and continued support.

The Lago Team


# Create add-ons

Add-ons are a useful feature that allows you to add a fixed charge that is not recurring to one-off invoices.  This can be used to apply one-time fees such as a setup fee, one-time payment, or customer success fee.

<Tabs>
  <Tab title="Dashboard">
    To create an add-on through the user interface, follow these steps:

    1.  Access the **"Add-ons"** section via the side menu;
    2.  Click **"Add an add-on"**;
    3.  Choose a name, a code, and a description (optional) for your add-on;
    4.  Define its default value and currency (these values can be overwritten when creating the invoice); and
    5.  Click **"Add add-on"** to confirm.
  </Tab>

  <Tab title="API">
    ```bash Create an add-on for "Setup Fees"
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request POST "$LAGO_URL/api/v1/add_ons" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "add_on": {
          "name": "Setup Fee",
          "code": "setup",
          "amount_cents": 50000,
          "amount_currency": "USD",
          "description": "Charge a setup fee for new customers."
        }
      }'
    ```
  </Tab>
</Tabs>

In the add-ons section, you can edit or delete add-ons by clicking the ellipsis icon.
Editing allows you to modify the name, code, description, and settings of the add-on, while deleting removes the add-on
from the list (this action cannot be undone). Please note that you cannot edit or delete an add-on that has already been applied
to a customer.

To assign an add-on to a customer, you need to create a one-off invoice.
Simply select the add-on(s) you wish to apply from the add-ons section while creating the invoice, and the fixed charge
will be added to the total amount due.


# Issue one-off invoices

One-off invoices allow you to bill immediately one or several add-ons to a customer.  This guide will show you how to create a one-off invoice for a specific customer using the add-ons.

## Create a one-off invoice

To create a one-off invoice for a specific customer:

1.  Select the customer from the list of customers; and
2.  Click the **"Actions"** button located in the upper-right corner and select **"Create one-off invoice"**.

## Adding add-ons to one-off invoices

Now that you have started the flow to create a one-off invoice, it's time to add one or several add-ons to it:

<Tabs>
  <Tab title="Dashboard">
    1.  Click **"Add an add-on"** to add a new add-on to the invoice;
    2.  Edit the number of units applied for a specific add-on;
    3.  Edit the unit price of a specific add-on (you can define it as 0 if needed);
    4.  Edit the description of the add-on displayed on the invoice; and
    5.  Click **"Create"** to issue your one-off invoice.

    <Frame caption="Adding add-ons to create a one-off invoice">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/one-off-invoices/images/one-off-invoices.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    ```bash Assign add-ons to create a one-off invoice
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"
    curl --location --request POST "$LAGO_URL/api/v1/invoices" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "invoice": {
          "external_customer_id": "hooli_1234",
          "currency": "USD",
          "fees": [
            {
              "add_on_code": "setup_fee",
              "units": 1,
              "unit_amount_cents": 50000,
              "description": "Implementation fee with a solution engineer"
            },
            {
              "add_on_code": "customer_success",
              "units": 2,
              "unit_amount_cents": 100000,
              "description": "One off customer success fee"
            }
          ]
        }
      }'
    ```
  </Tab>
</Tabs>

## Application scope of one-off invoices

Here are a few things to keep in mind about one-off invoices:

*   One-off invoices are issued immediately and can include the same add-on multiple times.
*   If the currency of the customer is already defined, the currency of the one-off invoice must be the same.
*   You can use the same add-on to create one-off invoices for multiple customers whose subscriptions don't have the same currency or to apply a different amount for one of these customers.
*   Coupons or prepaid credits (discounts) **do not apply** to one-off invoices.
*   One-off invoices are subject to taxes, as defined in the customer view.

<Tip>
  Note that when using the API endpoint, if the amount and currency are null, Lago will apply the default amount and currency defined in the UI.
</Tip>

## Invoicing

As mentioned previously, a **one-off invoice is invoiced straight away**. You are able to find one-off invoices through webhook with webhook message called `invoice.one_off_created`.


# Adyen integration

Lago's native integration with Adyen allows you to collect payments automatically when new invoices are generated.

Lago's seamless integration with Adyen offers a wide range of payment options, enabling you to conveniently collect payments from your customers. Supported payment methods include:

*   Card payments (Visa, MasterCard, CB)
*   Apple Pay
*   Paypal
*   American Express
*   Amazon Pay
*   Google Pay

And many more! With Lago's native Adyen integration, you can offer your customers a variety of payment options, enhancing their convenience and flexibility during transactions.

## Connecting Lago to Adyen

To set up the Adyen integration in Lago from our user interface, follow these steps:

1.  In the side menu of your Lago app, navigate to **Settings**;
2.  Select the **Integrations** tab;
3.  Click on **Adyen** and enter the required connection fields (described in the next section); and
4.  Click **Connect to Adyen** to confirm the integration.

## Adyen Connection Fields

When connecting Lago to Adyen, you need to provide information for the following fields.

<AccordionGroup>
  <Accordion title="1. API Key (mandatory)">
    The API Key is a mandatory field and can be found in your Adyen account. Follow these steps to retrieve the API Key:

    *   Go to your Adyen account and navigate to **Developers** > **API Credentials**;
    *   On the API Credentials page, create new credentials with a type of **Web service user**;
    *   Click on the **Create credentials** button to generate the API Key; and
    *   Copy the API Key and paste it in the corresponding field in Lago. Remember to save the changes.
  </Accordion>

  <Accordion title="2. Merchant Account (mandatory)">
    The Merchant Account is required to ensure that Lago targets the correct Adyen account. To find the Merchant Account:

    *   Go to **Settings** > **Merchant accounts** in your Adyen account; and
    *   Copy the **Account code** of the targeted account you want to use with Lago.
  </Accordion>

  <Accordion title="3. Live Prefix (optional)">
    The Live Prefix represents the prefix url of your live Adyen account. This field is optional. If left empty, you can connect a test account. However, for live accounts, you must provide a Live Prefix. Follow these steps to obtain the Live Prefix:

    *   Go to **Developers** > **API URLs** > **Prefix** in your Adyen account.
  </Accordion>

  <Accordion title="4. HMAC Signature (optional)">
    Adyen's HMAC signatures are used to protect webhook endpoints and messages created by Adyen. Lago requires this signature to properly decrypt outgoing webhooks from Adyen. To find the HMAC Signature:

    *   Create or edit a webhook in Adyen by accessing **Developers** > **Webhooks**; and
    *   Under "Security" settings, you can find the HMAC Key.

    <Tip>
      The Live Prefix and HMAC Signature fields are optional and may not be required depending on your use case.
    </Tip>
  </Accordion>
</AccordionGroup>

## Setting up Adyen's payments auto-capture

To enable automatic payment capture in your Adyen account, ensure that you have configured the account settings accordingly. Automatic payment capture allows for immediate processing without manual intervention. Refer to Adyen's documentation for instructions on [setting up auto capture](https://docs.adyen.com/online-payments/capture#automatic-capture).

## Turn on Adyen's recurring details

In Adyen, to enable recurring payments for a stored payment method, follow these steps:

1.  Go to Developers > Additional Data;
2.  Check the box for Recurring Details; and
3.  Click Save.

<Frame caption="Adyen recurring details option">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/adyen-recurring-options.png" />
</Frame>

## Setting up Adyen Webhook for listening to important events

**This step is crucial and mandatory** for Lago to receive and process messages from Adyen, enabling functionalities such as customer creation/update, payment processing, and refunds. To configure Adyen webhook and establish communication with Lago, follow the steps below:

1.  Access your Adyen application and navigate to the **Developers** section;
2.  Select **Webhooks** and create a new webhook of type **Standard**;
3.  In the **Server configuration** section, locate the **General** settings; and
4.  Copy and paste the following URL: **`https://api.getlago.com/webhooks/adyen/{{your_organization_id}}?code={{connection_code}}`**.

<Tip>
  You can find your Organization ID in Lago under the Developers section in Lago, specifically in **API keys & ID** > **Organization ID**.
</Tip>

<Tip>
  To find your **connection code**, navigate to the Integrations section in Lago and select the appropriate connection code for your Adyen integration.
</Tip>

**Please ensure that you complete this setup correctly, as your Adyen integration will not function without this vital step.**

## Setting Adyen as a Payment Provider for a customer

In order to facilitate automated payment collection, it is essential for the customer to exist in both the Lago and Adyen databases. Please note that in Adyen, customers are referred to as **Shoppers**.

### Adding a new customer in Adyen

If the customer does not already exist in Adyen, you can create them in Lago using either the user interface or the **[API](/api-reference/customers/create)**. When providing customer information, please ensure the following:

1.  Set Adyen as the customer's **default payment provider**;
2.  Keep the field associated with the **Adyen Payment Provider Customer ID** empty; and
3.  **Enable** the option to automatically create the customer in Adyen.

<Frame caption="Adyen as PSP for new customer">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/adyen-new-customer.png" />
</Frame>

Once the customer is added in Lago, they will be automatically synchronized with Adyen. Adyen will generate a unique Shopper ID, which will be stored in Lago. Typically, Adyen utilizes the Lago customer's **`external_id`** as the Shopper ID for seamless integration between the two platforms.

Upon successful customer creation, you will receive two **[webhook messages](/api-reference/webhooks/messages)** to keep you informed:

1.  **`customer.checkout_url_generated`**: This message includes the checkout URL that provides access to the default payment method. It allows you to perform a pre-authorization payment and store the payment method securely; and
2.  **`customer.payment_provider_created`**: This message confirms the successful creation of the customer in Adyen, indicating that the customer's details have been added to the Adyen database.

<Warning>
  Please note that the customer will be created in Adyen only if the payment method has been stored through the checkout URL and pre-authorization payment.
</Warning>

### Using an existing customer from Adyen

If the customer and direct debit mandate already exist in Adyen, you can create the customer record in Lago using either the user interface or **[the API](/api-reference/customers/create)**. Follow these steps when adding customer information:

1.  Set Adyen as the **default payment provider** for the customer in Lago; and
2.  Provide the **Adyen [Shopper Reference](https://docs.adyen.com/point-of-sale/card-acquisition/identifiers#:~:text=Shopper%20reference%3A%20a,contract%20payments.)** as the Lago **Payment provider customer ID**.
3.  **Disable** the option to automatically create the customer in Adyen.

By following these steps, you can integrate an existing customer from Adyen into Lago, ensuring synchronization and consistency between the two platforms.

<Frame caption="Adyen as PSP for existing customer">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/adyen-migration.png" />
</Frame>

## Adyen Checkout: storing customer's payment method information

When Lago automatically creates a customer in Adyen, you will receive a checkout link from Lago to facilitate the storage of your customer's payment method information.

The payload sent by Lago will have the following structure, with the checkout link stored under **`checkout_url`**:

```json
{
  "webhook_type": "customer.checkout_url_generated",
  "object_type": "payment_provider_customer_checkout_url",
  "payment_provider_customer_checkout_url": {
    "lago_customer_id": "88d23508-47fd-46bb-a87e-50c50f3cb371",
    "external_customer_id": "hooli_1234",
    "payment_provider": "adyen",
    "checkout_url": "https://test.adyen.link/PLEEA656869B11DF6B"
  }
}
```

<Info>
  Note: The checkout link automatically expires after 70 days.
</Info>

By utilizing this provided checkout link, your customers can perform a pre-authorization payment. It's important to note that the pre-authorization payment will not collect any funds from the customer. Once the pre-authorization is confirmed, Lago will send the payment method details and securely store them into Adyen for future transactions.

<Frame caption="Adyen checkout with Lago">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/adyen-checkout.png" />
</Frame>

## Creating payments from Lago Invoices

When a customer has Adyen defined as their payment provider, Lago seamlessly automates the process of triggering payments in Adyen whenever a new invoice is generated.

This integration ensures that payments are initiated in Adyen without any manual intervention. Lago's automatic payment creation saves time and effort, providing a streamlined experience for both you and your customers.

## Creating refunds from Lago Credit Notes

In cases where a customer has Adyen defined as their payment provider, Lago simplifies the refund process by automatically triggering refunds in Adyen whenever a new refund is initiated through credit notes.

This integration eliminates the need for manual refund processing and ensures that refunds are efficiently handled in Adyen. Lago's automated refund functionality helps you maintain accurate and timely refund transactions, enhancing customer satisfaction and operational efficiency.

## Payment disputes

In the event of a **lost** chargeback (dispute) within Adyen, Lago initiates an automatic response by marking the relevant invoice as disputed lost. This action involves populating the `dispute_lost_at` field with the timestamp when the dispute was lost. Following this update:

*   The invoice becomes non-voidable;
*   Generating a credit note is possible; however, refunding the payment back to the original payment method is not permitted; and
*   The invoice cannot be resent for collection.

## Watch the demo video

<iframe width="100%" height="400" src="https://www.youtube.com/embed/Zh7NNbgS7Bo" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />


# GoCardless integration

Lago's native integration with GoCardless allows you to collect payments via direct debit.

## Integration setup[](#integration-setup "Direct link to heading")

### Connect your GoCardless account[](#connect-your-gocardless-account "Direct link to heading")

To connect to GoCardless through the user interface:

1.  In the side menu, select **"Settings"**;
2.  Open the **"Integrations"** tab;
3.  Select **"GoCardless"** to be redirected to the GoCardless application;
4.  Create a GoCardless account or log in to your existing account; and
5.  Connect your account to be redirected to the Lago application.

When the OAuth connection is active, you will see the screen below, with your
secret key.

<Frame caption="Active OAuth connection with GoCardless">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/gcl-oauth-65c0e5a1a2767f606b55395e0ba394e4.png" />
</Frame>

### Create webhook endpoints[](#create-webhook-endpoints "Direct link to heading")

<Tip>
  To complete this process, you will need:

  *   Your Lago **organization ID**, available in the **"API keys & ID"** tab of the
      **"Developers"** section; and
  *   Your **secret key**, available in the **"Integrations"** tab of the
      **"Settings"** section ([learn more](#connect-your-gocardless-account)).
</Tip>

If you want Lago to automatically retrieve the status of the payments processed
via GoCardless, you must create a webhook endpoint in GoCardless. To do so:

1.  Log in to your [GoCardless account](https://manage.gocardless.com/sign-in);
2.  Go to the **"Developers"** section;
3.  In the upper right corner, click **"Create"** and then select **"Webhook endpoint"**;
4.  Choose a name for this webhook (e.g. Lago);
5.  Enter the following URL: `https://api.getlago.com/webhooks/gocardless/{{organization_id}}?code={{connection_code}}` (you must replace `{organization_id}` with your Lago organization ID, and the `{connection_code}` by the targeted Lago connection);
6.  Enter your secret key; and
7.  Click **"Create webhook endpoint"**.

<Frame caption="Webhook endpoint creation in GoCardless">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/gcl-webhook-9e1e96b038542112b1609ebb70a9dda9.png" />
</Frame>

In addition to this, you must create a webhook endpoint in Lago to retrieve the
checkout URL associated with each customer account
([learn more](#direct-debit)). To do so:

1.  Go to the **"Developers"** section of the Lago application;
2.  In the **"Webhooks"** tab, click **"Add a webhook"** on the right;
3.  Enter your webhook URL; and
4.  Click **"Add webhook"** to confirm.

For more information about our webhooks, please refer to the
[API documentation](/api-reference/webhooks/messages).

## Customer information[](#customer-information "Direct link to heading")

To collect payments automatically, the customer must exist in both the Lago and
GoCardless databases.

### New customer[](#new-customer "Direct link to heading")

If the customer does not already exist in GoCardless, you can first create them
in Lago, either via the user interface or
[the API](/api-reference/customers/create). When adding customer information, you
must:

1.  Provide the customer's email address;
2.  Define GoCardless as the **default payment provider**;
3.  Leave the field associated with the **GoCardless customer ID** blank; and
4.  **Enable** the option to automatically create the customer in GoCardless.

The customer will automatically be added to GoCardless. GoCardless will then
return the customer ID, which will be stored in Lago.

<Frame caption="Creation of a new customer with GoCardless">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/gcl-customer-new-3f7f52c1614edb8b577b075e35de99fb.png" />
</Frame>

When the customer is successfully created, you will receive two
[webhook messages](/api-reference/webhooks/messages):

*   `customer.payment_provider_created` that confirms the creation of the customer
    in GoCardless; and
*   `customer.checkout_url_generated` that includes the checkout URL to set up the
    direct debit ([learn more](#direct-debit)).

### Existing customer[](#existing-customer "Direct link to heading")

If the customer and direct debit mandate already exist in GoCardless, then you
should create the customer record in Lago, either via the user interface or
[the API](/api-reference/customers/create). When adding customer information, you
must:

1.  Provide the customer's email address;
2.  Define GoCardless as the **default payment provider**;
3.  Provide the **GoCardless customer ID**; and
4.  **Disable** the option to automatically create the customer in GoCardless.

<Frame caption="Migration of an existing GoCardless customer">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/gcl-customer-migration-959faab7b09d8c09866b477845ad8b3b.png" />
</Frame>

## Direct debit[](#direct-debit "Direct link to heading")

To collect payments via direct debit, a mandate must be created. To do so:

1.  Retrieve the checkout URL included in the `customer.checkout_url_generated` webhook; and
2.  Redirect your customer to the checkout page, so that they can complete the online form and approve the mandate.

The mandate must be validated by GoCardless before the first payment can be
processed. It can take up to six business days to validate a new mandate. For
more information about payment timings, please consult the
[GoCardless FAQ](https://gocardless.com/faq/merchants/direct-debit/).

<Warning>
  To collect payments via direct debit, the currency of the mandate must match
  the currency of the plan associated with the customer's subscription.
</Warning>

<Frame caption="Direct debit setup with GoCardless">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/gcl-mandate-c4e336d031a583d002189188ab2599e2.png" />
</Frame>

Each time a new invoice with an **amount greater than zero** is generated by
Lago, a payment will automatically be created. GoCardless will record the
invoice ID and process the payment. Payments via direct debit are usually
processed within five business days. If the payment is successful, the status of
the payment will switch from `pending` to `succeeded`.

If the payment fails, the status of the payment will switch from `pending` to
`failed` and Lago will generate an `invoice.payment_failure`
[webhook](/api-reference/webhooks/messages).

<Tip>
  If you have signed up for [GoCardlessSuccess+](https://gocardless.com/solutions/success-plus/), failed payments may
  be automatically resubmitted, in which case Lago will automatically update the
  invoice payment status.
</Tip>


# Overview

Connect Lago to any payment providers by using native integrations or webhook messages.

Lago helps you monitor usage and calculates how much each customer owes you. However, **Lago is not a payment service provider (PSP)**.

## Payment collection process

To collect payments from your customers, you can:

*   Use our native integrations with [GoCardless](/guide/payments/gocardless-integration), [Stripe Payments](/guide/payments/stripe-integration) or [Adyen](/guide/payments/adyen-integration); or
*   Use the [webhooks](/api-reference/webhooks/messages) sent by Lago to transmit billing information to your PSP (e.g. Paddle, Razorpay, Authorize.net, internal ledger, etc.).

Lago is **agnostic**, which means that you can use our billing solution with any PSP.

## Payment status

When payments are processed through one of our native integrations, the payment status of the invoice is **automatically updated**.

<Tabs>
  <Tab title="Dashboard">
    If needed, you can update the payment status via the user interface:

    1.  Access the **"Invoices"** section;
    2.  Select an invoice from the list;
    3.  Open the **"Actions"** dropdown menu in the upper right corner;
    4.  Click **"Update payment status"**;
    5.  Select the new payment status; and
    6.  Click **"Update status"** to confirm.
  </Tab>

  <Tab title="API">
    This action can be performed [via the API](/api-reference/invoices/update) as well by changing the `payment_status` argument.

    ```bash Update a payment status of an invoice
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request PUT "$LAGO_URL/api/v1/invoices/{__INVOICE_ID__}" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "invoice": {
        "payment_status": "succeeded",
        "metadata": [
          {...}
        ]
      }
    }'
    ```
  </Tab>
</Tabs>

## Handling one-off payments

Lago offers a streamlined solution for handling exceptional payment situations through its one-off payment checkout feature.
This is particularly useful when automatic payment processes face issues, resulting in invoices with `pending` or `failed` statuses.

*   **Instant checkout link generation:**
    For any troubled invoice, Lago enables you to generate a unique checkout link. This link can be shared with the user to facilitate an immediate payment of that invoice.

*   **Automatic payment method storage:**
    Lago captures and stores the payment method used in the one-off transaction. This ensures that future payments are processed more smoothly.

*   **Real-time payment status update:**
    The status of the invoice is updated in real time once the payment is successfully processed.

<Info>
  Currently, this feature is only supported for Adyen and Stripe native integrations with Lago.
</Info>


# Payment retries



Whether you use one of our native integrations or rely on our
[webhooks](/api-reference/webhooks/messages) to collect payments, you have the ability to
manually resend payments for collection when needed.

To re-trigger the payment process through the user interface:

1.  Access the **"Invoices"** section via the side menu;
2.  Open the **"Outstanding"** tab;
3.  Find the invoice for which you would like to collect payment;
4.  Click the **ellipsis icon** on the right; and
5.  Select **"Resend for collection"**.

<Frame caption="Payment retry via the invoice list">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/retry-payment.png" />
</Frame>

In the **"Outstanding"** and **"Overdue"** tabs of the **"Invoices"** section, you can also
click **"Resend for collection"** in the upper right corner to re-trigger the
payment process for all invoices in the respective lists.

<Info>
  Invoices that are overdue are available both on the **"Outstanding"** and the
  **"Overdue"** tabs. Make sure you resend for collection from the **"Overdue"**
  tab if you wish to collect payment for past due invoices only.
</Info>

When a payment is resent for collection, an `invoice.created` or
`invoice.add_on_added` webhook is automatically sent, depending on the type of
invoice.

In addition to this, if the default payment provider for the customer is
[Stripe](/guide/payments/stripe-integration),
[GoCardless](/guide/payments/gocardless-integration) or [Adyen](/guide/payments/adyen-integration), Lago will automatically process
the payment through integration.

It is also possible to trigger payment retries via the API
([learn more](/api-reference/invoices/retry.mdx)).


# Stripe integration

Lago's native integration with Stripe allows you to collect payments automatically when new invoices are generated.

## Watch the demo video

<iframe width="100%" height="400" src="https://www.youtube.com/embed/NH8MCMaHeFM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Integration setup[](#integration-setup "Direct link to heading")

To set up the integration with Stripe through the user interface:

1.  In the side menu, select **"Settings"**;
2.  Select the **"Integrations"** tab;
3.  Click **"Stripe"** and add a new connection;
4.  Give this new connection a name and a code;
5.  Enter your Stripe API key ([locate your API key](https://support.stripe.com/questions/locate-api-keys-in-the-dashboard)); and
6.  Click **"Connect to Stripe"** to confirm.

<Info>
  By default, customers created in Lago are not automatically created in Stripe.
  If you want your Lago customers to be added to Stripe, you need to activate
  this option ([learn more](#new-customer)).
</Info>

## Redirect url after checkout[](#checkout-redirect-url "Direct link to heading")

After establishing the connection with Stripe, set a success URL where your end customer will be directed after completing the checkout.
Please note that if it's not defined, your end customer will be redirected to Stripe's website.

Please note that you can edit or delete the redirect URL, and this will only affect new checkout URLs created.

<Warning>
  URL defined should always begin with `http://` or `https://`.
</Warning>

## Customer information[](#customer-information "Direct link to heading")

To collect payments automatically, the customer must exist in both the Lago and
Stripe databases.

### New customer[](#new-customer "Direct link to heading")

If the customer does not already exist in Stripe, you can first create them in
Lago, either via the user interface or [the API](/api-reference/customers/create).
When adding customer information, you must:

1.  Define Stripe as the **default payment provider**;
2.  Leave the field associated with the **Stripe customer ID** blank;
3.  **Enable** the option to automatically create the customer in Stripe; and
4.  Define payment method options for this customer. Possible values are `card`, `link`, `sepa_debit`, `us_bank_account` and `bacs_debit`.

The customer will automatically be added to Stripe. Stripe will then return the
customer ID, which will be stored in Lago.

<Frame caption="Creation of a new customer with Stripe">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/stripe-customer-new.png" />
</Frame>

### Existing customer[](#existing-customer "Direct link to heading")

If the customer already exists in Stripe but not in Lago, you should create the
customer record, either via the user interface or
[the API](/api-reference/customers/create). When adding customer
information, you must:

1.  Define Stripe as the **default payment provider**;
2.  Provide the **Stripe customer ID**;
3.  **Disable** the option to automatically create the customer in Stripe; and
4.  Define payment method options for this customer. Possible values are `card`, `link`, `sepa_debit`, `us_bank_account` and `bacs_debit`.

<Frame caption="Migration of an existing Stripe customer">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/stripe-customer-migration.png" />
</Frame>

## Supported payment methods

Lago's Stripe integration accommodates a variety of payment methods, both generic and region-specific.
The checkout URL provided by Lago is designed to handle multiple payment options seamlessly.

<AccordionGroup>
  <Accordion title="Card payments" icon="credit-card">
    Lago's Stripe integration includes a universal card payment method that supports various currencies, ideal for global transactions.
    This method is set as the default to facilitate recurring payments, ensuring Lago can process charges for your customers efficiently.

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

    curl --location --request POST "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "customer": {
          "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "address_line1": "5230 Penfield Ave",
          "billing_configuration": {
            "invoice_grace_period": 3,
            "payment_provider": "stripe",
            "provider_customer_id": "cus_12345",
            "sync": true,
            "sync_with_provider": true,
            "provider_payment_methods": ["card"]
          }
        }
      }'
    ```
  </Accordion>

  <Accordion title="SEPA debits (EU only)" icon="money-bill-transfer">
    For European customers, Lago supports Stripe SEPA Debit (Single Euro Payments Area).
    Accepting a mandate through this method authorizes you to debit your customers' accounts for recurring payments via Lago.
    The designated payment method for SEPA transactions within Lago is identified as `sepa_debit`.
    It's important to note that **this payment option is exclusive to invoices in `EUR` currency**.

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

    curl --location --request POST "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "customer": {
          "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "address_line1": "5230 Penfield Ave",
          "billing_configuration": {
            "invoice_grace_period": 3,
            "payment_provider": "stripe",
            "provider_customer_id": "cus_12345",
            "sync": true,
            "sync_with_provider": true,
            "provider_payment_methods": ["sepa_debit"]
          }
        }
      }'
    ```
  </Accordion>

  <Accordion title="ACH debits (US only)" icon="flag-usa">
    For US-based transactions, Lago integrates Stripe ACH Debit, leveraging the Automated Clearing House for electronic bank-to-bank payments.
    Upon accepting a mandate, you gain authorization to execute recurring debits from your customers' accounts through Lago.
    The designated payment method for ACH transactions within Lago is identified as `us_bank_account`.
    It's important to note that **this payment option is exclusive to invoices in `USD` currency**.

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

    curl --location --request POST "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "customer": {
          "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "address_line1": "5230 Penfield Ave",
          "billing_configuration": {
            "invoice_grace_period": 3,
            "payment_provider": "stripe",
            "provider_customer_id": "cus_12345",
            "sync": true,
            "sync_with_provider": true,
            "provider_payment_methods": ["us_bank_account"]
          }
        }
      }'
    ```
  </Accordion>

  <Accordion title="BACS debits (UK only)" icon="credit-card-front">
    For UK transactions, Lago integrates Stripe BACS Debit, utilizing the UK's BACS system for direct bank-to-bank payments.
    By accepting a mandate with this method, you're authorized to initiate recurring debits from your customers' accounts through Lago.
    The specific payment method for BACS transactions within Lago is designated as `bacs_debit`.
    It's important to note that **this payment method is exclusively for invoices in `GBP` currency.**

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

    curl --location --request POST "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "customer": {
          "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "address_line1": "5230 Penfield Ave",
          "billing_configuration": {
            "invoice_grace_period": 3,
            "payment_provider": "stripe",
            "provider_customer_id": "cus_12345",
            "sync": true,
            "sync_with_provider": true,
            "provider_payment_methods": ["bacs_debit"]
          }
        }
      }'
    ```
  </Accordion>

  <Accordion title="Link" icon="link">
    For card transactions, you can enable the [Link](https://stripe.com/payments/link) feature to offer one-click payments.
    Link automatically fills in your customers' payment information, ensuring a seamless and secure checkout experience.

    <Warning>
      If you are using the `link` feature, it must be used in conjunction with `card`.
    </Warning>

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

    curl --location --request POST "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "customer": {
          "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "address_line1": "5230 Penfield Ave",
          "billing_configuration": {
            "invoice_grace_period": 3,
            "payment_provider": "stripe",
            "provider_customer_id": "cus_12345",
            "sync": true,
            "sync_with_provider": true,
            "provider_payment_methods": ["card", "link"]
          }
        }
      }'
    ```
  </Accordion>
</AccordionGroup>

## Stripe Checkout: storing customer's payment method information

<Info>
  Checkout page shows only selected payment methods for customers.
</Info>

When Lago automatically creates a customer in Stripe, you will receive a checkout link from Lago to facilitate the storage of your customer's payment method information.

The payload sent by Lago will have the following structure, with the checkout link stored under `checkout_url`:

```json
{
  "webhook_type": "customer.checkout_url_generated",
  "object_type": "payment_provider_customer_checkout_url",
  "payment_provider_customer_checkout_url": {
    "lago_customer_id": "88d23508-47fd-46bb-a87e-50c50f3cb371",
    "external_customer_id": "hooli_1234",
    "payment_provider": "stripe",
    "checkout_url": "https://checkout.stripe.com/c/pay/prod_c15sTbBMLep5FKOA9b9pZBiRBBYYSU1IJ5T89I5TTtpKgzE380JSmxnVYz#fidkdWxOYHw"
  }
}
```

<Warning>
  Note: The checkout link automatically expires after 24 hours!
</Warning>

By utilizing this provided checkout link, your customers can perform a pre-authorization payment. It's important to note that the pre-authorization payment will not collect any funds from the customer. Once the pre-authorization is confirmed, Lago will send the payment method details and securely store them into Stripe for future transactions.

## Regenerate checkout link on demand

In cases where your end customer has not had the opportunity to complete the checkout process to inform their payment method
or wishes to modify the saved payment information, you can generate a new checkout link using the designated [endpoint](/api-reference/customers/psp-checkout-url).

```bash
POST /api/v1/customers/:customer_external_id/checkout_url
```

Upon successful generation, the new checkout link will be available in the endpoint response, and it will not be delivered through a webhook message.
It is important to note that the new link will inherit the same expiration setting as the original one.

It is crucial to be aware that if a customer is not associated with any payment provider, the response will contain an error message.

## Default payment method

When you add a new payment method in Stripe, **Lago automatically sets it as the default**.
This guarantees that Lago uses the latest payment method for a customer. However, if you manually designate one of
multiple payment methods as the default, Lago will use it for payments instead the most recent one.

## Payment intents[](#payment-intents "Direct link to heading")

Once Stripe is connected and the customer exists in both databases, you can
start collecting payments.

### Succeeded payments

Each time a new invoice with an **amount greater than zero** is generated by
Lago, a payment intent will automatically be created. Stripe will record the
invoice ID and process the payment. If the payment is successful, the status of
the payment will switch from `pending` to `succeeded`.

### Failed payments

If the payment fails, the status of the payment will switch from `pending` to
`failed` and Lago will generate an `invoice.payment_failure`
[webhook](/api-reference/webhooks/messages).

### Payments requiring validation

When a payment requires multi-step authentication, such as 3D Secure (3DS), Lago triggers a `payment.requires_action` [webhook](/api-reference/webhooks/messages#payment-requires-action).
This webhook provides the URL for completing the 3DS process. It's important to note that **most payments in India require 3DS authentication** due to [RBI regulations](https://www.rbi.org.in/Scripts/NotificationUser.aspx?Id=12051\&Mode=0).

### Minimum payment amount

If the new invoice amount falls below the [minimum amount supported by Stripe](https://stripe.com/docs/currencies#minimum-and-maximum-charge-amounts), the payment status will remain as `pending`.

<Warning>
  A valid payment method for the customer must be defined in Stripe for the
  payment intent to succeed ([learn how to save payment
  details](https://stripe.com/docs/payments/save-and-reuse)).
</Warning>

## Payment disputes

In the event of a **lost** payment dispute within Stripe, Lago initiates an automatic response by marking the relevant invoice as disputed lost. This action involves populating the `dispute_lost_at` field with the timestamp when the dispute was lost. Following this update:

*   The invoice becomes non-voidable;
*   Generating a credit note is possible; however, refunding the payment back to the original payment method is not permitted; and
*   The invoice cannot be resent for collection.


# Arrears vs Advance

Usage-based charges can be either charged in advance or in arrears

You have the flexibility to define the nature of charges associated with your products or services. Specifically, you can
**determine whether a charge has to be paid in arrears (at the end of the period), or in advance (immediately on event ingestion)**.

## Charges paid in arrears[](#charges-arrears "Direct link to heading")

If you opt for charges to be settled in arrears, they will be invoiced at the end of the billing period based on
the actual usage during that period. This payment option is ideal for usage types like storage, API calls, or compute,
where it is more practical to wait until the end of the period before billing. By default, all charges are configured to be
billed in arrears.

<Tabs>
  <Tab title="Dashboard">
    You can easily manage this billing settings through the user interface. Within the UI, you will find options to customize
    the invoice cadence by setting a charge as invoiced in arrears.

    <Frame caption="Define a charge paid in arrears">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/charge-in-arrears-1d16763a9e4212018386d79e400eea2a.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    Define `pay_in_advance : false` on a charge to bill it in arrears:

    <CodeGroup>
      ```bash Define a charge as paid in arrears {16, 22}
          LAGO_URL="https://api.getlago.com"
          API_KEY="__YOUR_API_KEY__"

          curl --location --request POST "$LAGO_URL/api/v1/plans" \
          --header "Authorization: Bearer $API_KEY" \
          --header 'Content-Type: application/json' \
          --data-raw '{
            "plan": {
              "name": "Premium",
              "code": "premium",
              "interval": "monthly",
              "description": "Premium plan for SMB companies",
              "amount_cents": 50000,
              "amount_currency": "USD",
              "trial_period": 0.0,
              "pay_in_advance": true,
              "bill_charges_monthly": true,
              "charges": [
                {
                  "billable_metric_id": "1111_2222_3333_4444",
                  "charge_model": "percentage",
                  "pay_in_advance": false,
                  "invoiceable": true,
                  "min_amount_cents": 100,
                  "properties": {
                    "rate": "0.5",
                    "fixed_amount": "1",
                    "free_units_per_events": 3,
                    "free_units_per_total_aggregation": null
                  }
                }
              ]
            }
          }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Charges paid in advance[](#charges-advance "Direct link to heading")

With this payment option, charges are invoiced immediately upon any changes in usage. It is particularly useful for scenarios
where you need to bill customers instantly for usage-based actions, such as new user seat or integrations.

<Tabs>
  <Tab title="Dashboard">
    You can easily manage this billing settings through the user interface. Within the UI, you will find options to customize
    the invoice cadence by setting a charge as invoiced in arrears.

    <Frame caption="Define a charge paid in arrears">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/charge-in-advance-5a13fc011d78a058f7767519c5817961.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    Define `pay_in_advance : true` on a charge to bill it in advance:

    <CodeGroup>
      ```bash Define a charge as paid in advance {16, 22}
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/plans" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "plan": {
          "name": "Premium",
          "code": "premium",
          "interval": "monthly",
          "description": "Premium plan for SMB companies",
          "amount_cents": 50000,
          "amount_currency": "USD",
          "trial_period": 0.0,
          "pay_in_advance": true,
          "bill_charges_monthly": true,
          "charges": [
            {
              "billable_metric_id": "1111_2222_3333_4444",
              "charge_model": "percentage",
              "pay_in_advance": true,
              "invoiceable": true,
              "min_amount_cents": 100,
              "properties": {
                "rate": "0.5",
                "fixed_amount": "1",
                "free_units_per_events": 3,
                "free_units_per_total_aggregation": null
              }
            }
          ]
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Custom price



<Info>
  **Premium feature ✨**:

  This feature is only available to users with a premium license. Please **[contact us](mailto:hello@getlago.com)** to get access this feature.
</Info>

Lago's basic interface and API allow you to configure prices using default price models, such as standard, graduated, or percentage-based models.
However, for more sophisticated products, you may need more complex pricing capabilities than those offered by Lago's default settings.

To meet this need, Lago can parse your custom code (using JSON), enabling you to implement advanced pricing rules for your charges.
This feature provides the flexibility to create tailored pricing models that precisely fit your product's requirements.
By leveraging custom code, you can ensure your pricing strategy is as dynamic and nuanced as your product demands.

This custom pricing can be set using the `custom_properties` attribute for a specific charge.
You can edit this custom price code and even overwrite it for a particular subscription.

Here is an example of a custom price model defining tiers across multiple properties:

```json
"properties": {
    "custom_properties": {
        "ranges": [
            { "from": 0, "to": 10, "storage_eu": "0", "storage_us": "0", "storage_asia": "0" },
            { "from": 10, "to": 20, "storage_eu": "0.10", "storage_us": "0.20", "storage_asia": "0.30" },
            { "from": 20, "to": null," storage_eu": "0.20", "storage_us": "0.30", "storage_asia": "0.40" }
        ]
    }
}
```


# Dynamic



<Note>
  Only the `sum` aggregation type is compatible with the `dynamic` charge model.
  If you have a different use case, please reach out to the Lago team for assistance.
</Note>

Select the dynamic charge model if you calculate the price manually or if prices fluctuate during a billing period (e.g., for SMS APIs, AI models, etc.), and you want to apply a specific **total amount** per event using the property `precise_total_amount_cents`.

Let’s take the example of our AI company. You may want to charge a custom price per event. Consider the following list of events:

<Tabs>
  <Tab title="Table view">
    | Event         | Metric             | Unit | Total amount |
    | ------------- | ------------------ | ---- | ------------ |
    | Transaction 1 | Dedicated Instance | 7    | \$0.70       |
    | Transaction 2 | Dedicated Instance | 5    | \$0.55       |
    | Transaction 3 | Dedicated Instance | 10   | \$2.20       |
  </Tab>

  <Tab title="Events payload">
    <CodeGroup>
      ```bash List of events
      {
        "events": [
          {
            "transaction_id": "transaction_1",
            "external_subscription_id": "123456789",
            "code": "dedicated_instance",
            "timestamp": 1728554400,
            "precise_total_amount_cents": "70", //event total amount
            "properties": {
              "unit": "7"
            }
          },
          {
            "transaction_id": "transaction_2",
            "external_subscription_id": "123456789",
            "code": "dedicated_instance",
            "timestamp": 1728558000,
            "precise_total_amount_cents": "55", //event total amount
            "properties": {
              "unit": "5"
            }
          },
          {
            "transaction_id": "transaction_3",
            "external_subscription_id": "123456789",
            "code": "dedicated_instance",
            "timestamp": 1728561600,
            "precise_total_amount_cents": "220", //event total amount
            "properties": {
              "unit": "10"
            }
          }
        ]
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

At the end of the period, the invoice will generate **one fee of \$3.435** (see example bellow).

| Item               | Unit | Unit price | Amount |
| ------------------ | ---- | ---------- | ------ |
| Dedicated Instance | 22   | \$0,156818 | \$3.45 |

To display more detailed information on fees, please refer to the [custom invoice grouping](/guide/invoicing/overview#custom-invoice-grouping) or the [pay in advance](/guide/plans/charges/arrears-vs-advance#charges-paid-in-advance) option.

<Note>
  Only the `standard` & `dynamic` charge models support the [custom invoice grouping](/guide/invoicing/overview#custom-invoice-grouping).
</Note>


# Graduated



Select the graduated charge model if you want to define **several price tiers**.
This charge model allows you to apply a discount depending on the number of
units consumed. You can also apply a **flat fee** to an entire tier.

Let's take back the example of the API company. You could charge \$1 per unit for
the first 100 units (first 100 API calls), then \$0.50 per unit for the next 100
calls and finally, \$0.10 for any additional unit.

Please refer to the tooltip in the user interface for more information.

<Frame caption="Configuration of the graduated charge model">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/graduated-charge-pricing-model-65dd3d428a7a5aaeb486e851adf029e7.png" />
</Frame>


# Graduated percentage



Select the graduated percentage model if you want to define several percentage tiers. You can also
apply a **flat fee** per tier in addition to the rate.
Note that the **rate** is the only mandatory value. It's particularly useful for fintech charging graduated rates for a feature.

Consider the following example, where each unit represents an API call:

| Tier   | First unit | Last unit | Rate | Flat fee |
| ------ | ---------- | --------- | ---- | -------- |
| Tier 1 | 0          | 1,000     | 1%   | \$200    |
| Tier 2 | 1,001      | 10,000    | 2%   | \$300    |
| Tier 3 | 10,001     | ∞         | 3%   | \$400    |

A first transaction at \$500 would cost (500 units x 1%) + \$200 flat fee = \$205.00;
A second transaction at \$550 would cost \[(500 units x 1%)  + (50 units x 2%)] + \$300 flat fee = \$306.00;
A third transaction at \$4,000 would cost (4,000 x 2%) = \$80.00.

<Tip>
  Unlike the fixed fee, **the flat fee is applied to the entire tier**, rather than per transaction.
</Tip>


# Package



Select the package charge model if you want to apply a **fixed price to a range
of units**. You also have the ability to offer free units.

Let's take back the example of our API company. You may want to charge \$5 per
100 units and offer the first 100 units. In this example, 201 units would cost
\$0 (first 100 units) + \$5 (next 100 units) + \$5 (last unit) = \$10.

<Frame caption="Configuration of the package charge model">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/package-pricing-charge-model-ff1836a27a037aaf14819bbdb70c836b.png" />
</Frame>


# Percentage



Select the percentage charge model if you want to apply a **percentage and a
fixed fee on transactions** (e.g. bank transfers, ATM withdrawals, etc.).

This charge model is generally used with billable metrics that allow users to
calculate the total amount of transactions (e.g. `sum` aggregation type and
`amount` defined as the event property -
[learn more](/guide/billable-metrics/aggregation-types)).

You can define several parameters for the percentage charge model, including:

*   **Percentage rate**: charge rate that applies to the total amount (e.g. 1.2%
    on transactions);
*   **Fixed fee (optional)**: fee that applies to each event ingested during the
    billing period (e.g. \$0.10 per transaction);
*   **Free units (per event - optional)**: number of events that are not subject to
    the fixed fee;
*   **Free units (total amount - optional)**: amount that is not subject to the
    charge rate;
*   **Per-transaction spending minimum (per event - optional)**: sets the minimum amount of spending required for each individual transaction; and
*   **Per-transaction spending maximum (per event - optional)**: sets the maximum amount of spending required for each individual transaction.

When free units are defined for both the total amount and number of events, Lago
performs checks each time a new event is ingested to determine whether the free
units still apply. In the illustration below for instance, the first 3 events or
\$500 are free.

<Info>**Premium feature ✨**: only users with a premium license can define a per-transaction spending minimum and maximum for the percentage pricing model.
Please **[contact us](mailto:hello@getlago.com)** to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

<Frame caption="Configuration of the percentage charge model">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/percentage-model-b2657bc04ac57c27cfe3bc3b830fd8dc.png" />
</Frame>

Consider the following list of events:

| Event         | Amount | Total number of events         | Total amount       | Result     |
| ------------- | ------ | ------------------------------ | ------------------ | ---------- |
| Transaction 1 | \$200  | 1 free event (out of 3)        | \$200 (\$500 free) | No charges |
| Transaction 2 | \$100  | 2 free events (out of 3)       | \$300 (\$500 free) | No charges |
| Transaction 3 | \$100  | 3 free events (out of 3)       | \$400 (\$500 free) | No charges |
| Transaction 4 | \$50   | 4 events (free units exceeded) | \$450 (\$500 free) | Charge     |

Therefore, for the fourth transaction, the charge will be \$0.10 x 1 event + 1.2%
of \$50 = \$0.70.


# Standard



Select the standard charge model if you want to charge the **same price for each
unit** consumed.

Imagine that your API company charges \$0.05 per API call (i.e. your billable
metric). By selecting the standard charge model, you will define a fixed unit
price. If a customer makes 1,000 API calls during the billing period, the total
invoice amount will be \$0.05 x 1,000 API calls = \$50.

<Note>
  Only the `standard` & `dynamic` charge models support the [custom invoice grouping](/guide/invoicing/overview#custom-invoice-grouping).
</Note>


# Volume



Select the volume charge model if you want to define several price tiers but
want to apply a **single unit price based on the total volume**. You can also
apply a **flat fee** in addition to the unit price.

Consider the following example, where each unit represents an API call:

| Tier   | First unit | Last unit | Unit price | Fixed fee |
| ------ | ---------- | --------- | ---------- | --------- |
| Tier 1 | 0          | 10,000    | \$0.0010   | \$10      |
| Tier 2 | 10,001     | 50,000    | \$0.0008   | \$10      |
| Tier 3 | 50,001     | 100,000   | \$0.0006   | \$10      |
| Tier 4 | 100,001    | ∞         | \$0.0004   | \$10      |

In this case, 65,000 API calls would cost 65,000 x \$0.0006 + \$10 = \$49.


# Charges with filters

Charge your customers by leveraging a combination of filters specified in the billable metric.

## Define a price for a combination of filters[](#define-price-for-filters "Direct link to heading")

When a billable metric has defined filters, establish a set of filters to refine an event and assign a price to this combination.

<Tabs>
  <Tab title="Dashboard">
    1.  Add a charge to a plan (this charge should be associated with a billable metric containing filters);
    2.  Add a new filter;
    3.  Choose a combination of filters, either specifying a key and its value or simply the key itself (covering all values);
    4.  Set a price for this combination of filters; and
    5.  Optionally, provide an Invoice display name.

    <Frame caption="Set a price for a combination of filters">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/charge-with-filters.gif" />
    </Frame>
  </Tab>

  <Tab title="API">
    Here are an example of plans you can create:

    <CodeGroup>
      ```bash Charge with filters {22-43}
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/subscriptions" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "name": "Standard plan",
          "code": "standard_plan",
          "interval": "monthly",
          "pay_in_advance": false,
          "amount_cents": 1000,
          "amount_currency": "USD",
          "charges": [
            {
              "billable_metric_id": "5d387072-e1f2-416f-b981-135c2f177069",
              "invoice_display_name": null,
              "charge_model": "standard",
              "properties": {
                "amount": "2"
              },
              "filters": [
                {
                  "values": {
                    "region": ["africa"],
                    "provider": ["aws"]
                  },
                  "invoice_display_name": "Africa & AWS",
                  "properties": {
                    "amount": "1"
                  }
                },
                {
                  "values": {
                    "region": ["__ALL_FILTER_VALUES__"],
                    "provider": ["__ALL_FILTER_VALUES__"]
                  },
                  "invoice_display_name": "Other regions and providers",
                  "properties": {
                    "amount": "0.5"
                  }
                }
              ]
            }
          ]
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Define a default price[](#define-default-price "Direct link to heading")

When a billable metric has filters defined, set a default price on the charge level to cover all the other combination of filters not defined in the charge.

<Tabs>
  <Tab title="Dashboard">
    1.  Add a charge to a plan (this charge should be associated with a billable metric containing filters);
    2.  Add a default price;
    3.  Set a price for this default price

    <Frame caption="Set a default price for a charge handling groups">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/charge-with-groups-default-price.gif" />
    </Frame>
  </Tab>

  <Tab title="API">
    Here are an example of plans you can create:

    <CodeGroup>
      ```bash Storage
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/subscriptions" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "name": "Standard plan",
          "code": "standard_plan",
          "interval": "monthly",
          "pay_in_advance": false,
          "amount_cents": 1000,
          "amount_currency": "USD",
          "charges": [
            {
              "billable_metric_id": "5d387072-e1f2-416f-b981-135c2f177069",
              "invoice_display_name": null,
              "charge_model": "standard",
              "properties": {
                "amount": "2"
              }
            }
          ]
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<br />

<Tip>
  If the default price is not set, Lago will automatically define it as 0 based on the charge model.
</Tip>


# Invoiceable vs Uninvoiceable

In-advance charges can be either invoiceable or not.

<Info>
  **Premium feature ✨**: only users with a premium license can define whether
  or not a charge is invoiceable. Please **[contact
  us](mailto:hello@getlago.com)** to get access to Lago Cloud and Lago
  Self-Hosted Premium.
</Info>

If a charge needs to be `paid in advance`, you can choose whether or not it generates an invoice.

The `"invoiceable": false` option is **particularly relevant for fintech companies that want to charge customers instantly
without issuing an invoice**. This feature can be useful for banking transactions like ATM withdrawals, FX transfers and other
similar scenarios.

By setting the invoiceable parameter to false, a fee is created by default, and a webhook `fee.created` is sent immediately upon any changes in usage without generating an invoice. However, you can configure the charge invoicing strategy via `regroup_paid_fees`:

1.  `null`: Fees generated never appear on invoices (default behaviour).
2.  `invoice`: Groups all paid fees into one invoice at the end of the billing period.

Please note that if `invoice`, all fees generated with a `payment_status` different from `succeeded` won’t appear on invoice generated at the end of the billing period. They will appear on next ones if you manually edit their `payment_status` to `succeeded`.

The invoice generated consolidates paid fees, is marked as paid, and will not be emailed to your end customer if the email feature is activated.

<Tabs>
  <Tab title="Dashboard">
    1.  Go to a **Plan**;
    2.  Add a usage-based **charge**;
    3.  Define a price model;
    4.  Define this charge as **paid in advance**; and
    5.  Select the option that best suits your needs from the three available choices.

    <Frame caption="Configure the charge invoicing strategy">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/instant-charge.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    Use the `invoiceable : false` for a charge paid in advance:

    <CodeGroup>
      ```bash Define a charge as invoiceable or not {23}
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/plans" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "plan": {
          "name": "Premium",
          "code": "premium",
          "interval": "monthly",
          "description": "Premium plan for SMB companies",
          "amount_cents": 50000,
          "amount_currency": "USD",
          "trial_period": 0.0,
          "pay_in_advance": true,
          "bill_charges_monthly": true,
          "charges": [
            {
              "billable_metric_id": "1111_2222_3333_4444",
              "charge_model": "percentage",
              "pay_in_advance": true,
              "invoiceable": false,
              "regroup_paid_fees" : "invoice"
              "min_amount_cents": 100,
              "properties": {
                "rate": "0.5",
                "fixed_amount": "1",
                "free_units_per_events": 3,
                "free_units_per_total_aggregation": null
              }
            }
          ]
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Metered vs Recurring

Usage-based charges can be either metered or recurring

You have the flexibility to define the nature of charges associated with your products or services. Specifically, you can
**determine whether a charge is metered or recurring**. Understanding the distinction between these two types of charges is crucial for
effectively managing your billing processes. In this documentation, we will delve into the differences between metered and
recurring charges and their implications within the Lago system.

## Metered charges[](#metered "Direct link to heading")

<Tabs>
  <Tab title="Dashboard">
    When you create a metered billable metric in Lago by setting the `recurring` parameter to `false`, an important behavior comes into play.
    At the end of each billing period, the accumulated number of units associated with the metric is automatically reset to 0.
    This means that the counting or measuring of units starts fresh with each new billing cycle. This is ideal for billing components with results
    that are not persisted billing periods over billing periods.

    In the API tab beside, consider the example of a **Storage billing unit**. If you need to **track the Gigabytes stored during a month**,
    it's important to note that this value should be reset to 0 at the beginning of each new month.
  </Tab>

  <Tab title="API">
    Create a billable metric with `recurring` sets to `false`.

    <CodeGroup>
      ```bash Metered billable metric {13}
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"

        curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
            "billable_metric": {
            "name": "Storage",
            "code": "storage",
            "description": "GB of storage used in my application",
            "aggregation_type": "sum_agg",
            "recurring": false,
            "field_name": "gb",
            "group": {
                "key": "region",
                "value": ["us-east-1", "us-east-2", "eu-west-1"]
            }
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Recurring charges[](#recurring "Direct link to heading")

<Tabs>
  <Tab title="Dashboard">
    When you create a recurring billable metric in Lago with the recurring parameter set to true, an important behavior comes
    into effect. At the end of each billing period, the accumulated number of units calculated from the previous billing period is
    carried forward to the next billing period.

    This means that the counting or measurement of units starts based on the last recorded value from the previous billing cycle.
    This behavior is particularly useful for billing components or services where the results need to persist from one billing period
    to another.

    In the API tab, let's consider the example of a **Seats billing unit**. If you need to **track the number of active seats**, it's crucial to
    note that this value should persist month over month. The recurring billing behavior ensures that the count of active seats is
    maintained and carried forward to subsequent billing periods, providing accurate and continuous tracking of your subscription seats.
  </Tab>

  <Tab title="API">
    Create a billable metric with `recurring` sets to `true`.

    <CodeGroup>
      ```bash Recurring billable metric {13}
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"

        curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
            "billable_metric": {
            "name": "Seats",
            "code": "seats",
            "description": "Active seats.",
            "aggregation_type": "count_unique",
            "recurring": true,
            "field_name": "seat_id",
            "group": {
                "key": "type",
                "value": ["admin", "viewer", "editor"]
            }
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Overview

In addition to the price of the plan, you can charge your customers for usage.

## Overview of charges[](#overview-of-charges "Direct link to heading")

To incorporate usage-based charges into a plan, you can utilize existing billable metrics.
This enables you to offer "pay-as-you-go" features.
For instance, you can create charges based on the number of API calls, the
number of active users, transactions, compute time, etc. These additional
charges relate to the [billable metrics](/guide/billable-metrics/create-billable-metrics) defined previously.
Here are some important details to consider regarding usage-based charges:

## Currency of charges[](#charges-currency "Direct link to heading")

All charges are denominated in the same currency as the plan to ensure consistency and transparency.

## Trial period exclusions[](#trial-period-exclusion "Direct link to heading")

It's important to note that the trial period exclusively applies to the base amount of the plan and does not extend
to usage-based charges.

## Number of decimals[](#number-of-decimals "Direct link to heading")

Lago allows you create charges with up to fifteen decimals (e.g.
\$0.000123456789123).

Please note that charges are invoiced in `amount_cents`. Therefore, Lago
automatically rounds prices (e.g. USD 1102 `amount_cents` = \$11.02).

## Delete a charge[](#delete-charge "Direct link to heading")

You may delete a charge included in a plan associated with existing
[subscriptions](/guide/subscriptions/assign-plan).

If you do so and save the change:

*   The charge will be immediately removed from all subscriptions linked to this
    plan;
*   The charge will no longer be included in the
    [current usage](/api-reference/customer-usage/customer-usage-object) of the customers
    concerned; and
*   The charge will be immediately removed from all `draft` invoices associated
    with these subscriptions.

However, the charge will still be included in all `finalized` invoices
associated with these subscriptions.

<Info>
  Deleting a charge does not delete the events associated with the corresponding
  billable metric. If later you decide to add the charge back into the plan, the
  events received before the deletion may be taken into account in the billing
  process (depending on the limits of the billing period).
</Info>

<Frame caption="How to delete a charge">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/charges-delete-e8b82428bc7fe73f40f419fb6ee88dab.png" />
</Frame>

## Update invoice display names[](#invoice-display-names "Direct link to heading")

When creating or updating a charge within our system, you have the flexibility to customize the way it
appears by overriding its default name. This can be achieved by defining an `invoice display name` for the charge.
By doing so, the newly specified name will take precedence and be reflected across all relevant contexts,
including prominently on the invoice template.

<Frame caption="How to modify the invoice display name">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/invoice-display-name.gif" />
</Frame>


# Prorated vs Full

Usage-based charges can be either bill fully or prorated based on the number of days used.

You can **determine whether a charge is prorated or fully-billed**. Understanding the distinction between these two types of
charges is crucial for effectively managing your billing processes. In this documentation, we will delve into the differences
between prorated and fully-billed charges and their implications within the Lago system.

## Prorated charges[](#prorated "Direct link to heading")

<Tabs>
  <Tab title="Dashboard">
    <Warning>
      Only charges that are [recurring](#2-recurring-charges) (billable metric with `recurring` argument sets to `true`) with a `charge_model` defined to `standard`, `graduated` or `volume` can be prorated.
    </Warning>

    When creating a prorated charge in Lago with the `prorated` parameter set to `true`, an important behavior is triggered.
    Adding a new unit during the billing period results in the amount due for that unit being prorated based on the number of
    days it was used.

    This means that your customers will only be charged for the actual number of days they utilized a billing unit. Let's **consider
    the example of prorated `Seats`**, where each seat costs \$10. If a new seat is added on June 10th, the unit will be prorated for 22 days, resulting in a corresponding prorated charge for that duration. This ensures fair and accurate billing based on the
    usage period.

    *Example: (1 Seat x \$10), used for 22 days = \$7.33*

    By leveraging prorated charges in Lago, you can provide transparent and cost-effective billing for services that are added or
    removed mid-billing cycle, adjusting the charges according to the actual duration of usage.
  </Tab>

  <Tab title="API">
    Create a charge that is prorated by setting `prorated` to `true`.

    <Warning>
      Only charges that are [recurring](#2-recurring-charges) (billable metric with `recurring` argument sets to `true`) with a `charge_model` defined to `standard` or `volume` can be prorated.
    </Warning>

    <CodeGroup>
      ```bash Prorated charges {25}
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"

        curl --location --request POST "$LAGO_URL/api/v1/plans" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "plan": {
            "name": "Startup",
            "code": "startup",
            "interval": "monthly",
            "description": "This is a basic plan description",
            "amount_cents": 10000,
            "amount_currency": "USD",
            "trial_period": 3.0,
            "pay_in_advance": true,
            "bill_charges_monthly": false,
            "charges": [
              {
                "billable_metric_id": "__BILLABLE_METRIC_ID__",
                "charge_model": "standard",
                "pay_in_advance": true,
                "invoiceable": true,
                "min_amount_cents": 0,
                "prorated": true,
                "group_properties": [
                  {
                    "group_id": "__GROUP_ID__",
                    "values": {
                      "amount": "10"
                    }
                  }
                ]
              }
            ]
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Fully-billed charges[](#fully-billed "Direct link to heading")

<Tabs>
  <Tab title="Dashboard">
    <Warning>
      Note that metered charges (billable metrics with `recurring` sets to `false`) are automatically fully-billed.
    </Warning>

    When creating a fully-billed charge in Lago with the `prorated` parameter set to `false`, an important behavior occurs.
    If a new unit is added during the billing period, the amount due for that unit is billed in full, regardless of the number of
    days it was used.

    This means that your customers will be charged for the entire billing period, even if they only utilized the billing unit for a
    few days. **Let's consider the example of fully-billed Seats**, where each seat costs \$10. If a new seat is added on June 10th, it will
    be billed for the full billing period. For instance, if there is one seat that was used for 22 days in the billing period, the
    charge would be calculated as follows:

    *(1 Seat x \$10), used for 22 days = \$10.*

    By utilizing fully-billed charges in Lago, you ensure that you do not lose revenue by billing customers for the entire billing period,
    regardless of the actual duration of usage.
  </Tab>

  <Tab title="API">
    Create a charge that is billed fully by setting `prorated` to `false`.

    <CodeGroup>
      ```bash Fully-billed charges {25}
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"

        curl --location --request POST "$LAGO_URL/api/v1/plans" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "plan": {
            "name": "Startup",
            "code": "startup",
            "interval": "monthly",
            "description": "This is a basic plan description",
            "amount_cents": 10000,
            "amount_currency": "USD",
            "trial_period": 3.0,
            "pay_in_advance": true,
            "bill_charges_monthly": false,
            "charges": [
              {
                "billable_metric_id": "__BILLABLE_METRIC_ID__",
                "charge_model": "standard",
                "pay_in_advance": true,
                "invoiceable": true,
                "min_amount_cents": 0,
                "prorated": false,
                "group_properties": [
                  {
                    "group_id": "__GROUP_ID__",
                    "values": {
                      "amount": "10"
                    }
                  }
                ]
              }
            ]
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Spending minimums



<Info>**Premium feature ✨**: only users with a premium license can define a charge spending minimum.
Please **[contact us](mailto:hello@getlago.com)** to get access to Lago Cloud and Lago Self-Hosted Premium.</Info>

Usage-based charges are always paid at the end of the billing period, based on the amount of consumption that occurred. However, you
could possibly need to define a spending minimum that a customer needs to commit to.

If your customer spends less than the committed amount, you will **charge a true-up fee equal to the difference between the commitment
and the actual usage**. Please note that this true-up fee is tied to the initial charge but will appear as a separate line item in an
invoice or in a credit note.

**Spending minimums and true-up fees are always prorated based on the number of days used in the subscription**. This ensures
fairness if your customer signs up at the end of the month, upgrades to a new plan, or terminates an ongoing subscription
before the end of the period.

In the example below, a customer is billed based on Monthly Tracked Users (MTU), with a standard pricing of \$0.010 per tracked users.
However, the customer is committed to a spending minimum of \$100. If the total consumption of MTUs for the period is \$50, a true-up fee
of \$50 will be charged.

To define a charge spending minimum:

<Tabs>
  <Tab title="Dashboard">
    1.  Go to a **Plan**;
    2.  Add a usage-based **charge**;
    3.  Define a price model;
    4.  Click the add a **spending minimum** button; and
    5.  Define a spending minimum **amount**.
  </Tab>

  <Tab title="API">
    Use the `min_amount_cents` field on a charge:

    <CodeGroup>
      ```bash Spending minimum for a charge {24}
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/plans" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "plan": {
          "name": "Premium",
          "code": "premium",
          "interval": "monthly",
          "description": "Premium plan for SMB companies",
          "amount_cents": 50000,
          "amount_currency": "USD",
          "trial_period": 0.0,
          "pay_in_advance": true,
          "bill_charges_monthly": true,
          "charges": [
            {
              "billable_metric_id": "1111_2222_3333_4444",
              "charge_model": "percentage",
              "pay_in_advance": false,
              "invoiceable": true,
              "min_amount_cents": 100,
              "properties": {
                "rate": "0.5",
                "fixed_amount": "1",
                "free_units_per_events": 3,
                "free_units_per_total_aggregation": null
              }
            }
          ]
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Commitments



<Info>
  **Premium feature ✨**:

  This feature is only available to users with a premium license. Please **[contact us](mailto:hello@getlago.com)** to get access to Lago Cloud and Lago Self-Hosted Premium.
</Info>

In your plan configuration, Lago provides the flexibility to define specific spending commitments tailored to your business needs.
These commitments serve as a financial baseline for the services you offer. However, understanding the unique requirements of each customer,
Lago offers the capability to customize these commitments on a per-customer basis at the time of creating a subscription.

## Minimum commitment

### Guidelines

Besides setting [spending minimums per charge](/guide/plans/charges/spending-minimum), Lago also allows you to define minimum invoice totals.
This ensures customers meet a minimum spend per billing period, securing a steady revenue flow and aiding in accurate financial forecasting.
The minimum commitment per invoice set in Lago applies to all charges.

*   **Commitment interval:** The minimum commitment is aligned with the billing interval of the plan. For instance, if the plan is billed monthly, the minimum commitment is also established on a monthly basis;
*   **Customizable commitments:** When assigning a plan to a customer, you have the option to override the default commitment. This allows for customized minimum commitments per customer, accommodating negotiated contract terms; and
*   **Arrears calculation:** The commitment is calculated in arrears, meaning Lago waits until the end of the billing period to assess whether users have met their minimum spending commitment. This approach ensures accurate billing based on actual usage.

### True-up fee

If the total spending falls below the minimum commitment at the end of the billing period, Lago will **apply a true-up fee to adjust the invoice and meet the minimum spending requirement**.
Conversely, if spending exceeds the minimum commitment, Lago will generate an invoice for the actual consumption, without issuing a true-up fee.

<Info>
  The minimum commitment is calculated based on the pre-tax amount and before any discounts (such as coupons or credits) are applied.
</Info>

### Defining a minimum commitment

<Tabs>
  <Tab title="Dashboard">
    To create or update a minimum commitment from the user interface:

    1.  Access an existing or a new plan **"Plan"**;
    2.  Navigate below usage based charges;
    3.  Define a **minimum commitment**; and
    4.  Click **"Add plan"** to confirm.

    <Frame caption="Define a minimum commitment">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/minimum-commitment-on-plan.png" />
    </Frame>

    <Info>
      The minimum commitment must follow the plan's interval. You can add a specific tax rate for this minimum commitment.
    </Info>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```json Define a minimum commitment {16-22}
      {
          "plan": {
            "name": "Basic",
            "invoice_display_name": null,
            "created_at": "2024-02-23T16:01:04Z",
            "code": "basic",
            "interval": "monthly",
            "description": "",           
            "amount_cents": 10000,
            "pay_in_advance": true,
            "bill_charges_monthly": null,
            "customers_count": 2,
            "active_subscriptions_count": 2,
            "draft_invoices_count": 0,
            "parent_id": null,
            "minimum_commitment": {
              "plan_code": "basic",
              "invoice_display_name": "Minimum Contract Commitment",
              "amount_cents": 50000,
              "interval": "monthly",
              "taxes": []
              },
            "charges": [
                {
                  "id": "ca205886-cf09-4e42-aed6-34cb2afd0c29",
                  "billable_metric_id": "5b320600-715b-4ef5-88c1-4f88c0ec5c50",
                  "invoice_display_name": "",
                  "billable_metric_code": "storage",
                  "created_at": "2024-02-23T16:01:04Z",
                  "charge_model": "standard",
                  "invoiceable": true,
                  "pay_in_advance": false,
                  "prorated": false,
                  "properties": {
                      "amount": "1"
                  },
                  "group_properties": [],
                  "taxes": []
                },
                {
                  "id": "1d5c78c6-0e22-424f-af8d-6784f6ff44ec",
                  "billable_metric_id": "4cbc5940-32fb-48a8-aa39-ad664b34a062",
                  "invoice_display_name": null,
                  "billable_metric_code": "seats",
                  "created_at": "2024-02-23T16:04:09Z",
                  "charge_model": "standard",
                  "invoiceable": true,
                  "pay_in_advance": true,
                  "prorated": false,
                  "min_amount_cents": 0,
                  "properties": {
                      "amount": "7"
                  },
                  "group_properties": [],
                  "taxes": []
                }
              ],
            "taxes": []
          }
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Overwriting a minimum commitment

<Tabs>
  <Tab title="Dashboard">
    To overwrite the minimum commitment for a specific customer, follow these instructions:

    1.  Access a specific customer;
    2.  Choose to assign a new plan or edit an existing subscription; and
    3.  Override the default plan's minimum commitment with a new value.

    <Frame caption="Overwriting a minimum commitment">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/overwriting-minimum-commitment.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```json Define a minimum commitment
          {
          "subscription": {
            "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
            "plan_code": "premium",
            "name": "Repository A",
            "external_id": "my_sub_1234567890",
            "billing_time": "anniversary",
            "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": [],
              "minimum_commitment": {
                "plan_code": "basic",
                "invoice_display_name": "Minimum Contract Commitment",
                "amount_cents": 50000,
                "interval": "monthly",
                "taxes": []
              }
              "charges": []
            }
          }
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Overview

If Billable metrics are made to measure customer usage, Plans are made to apply prices to this usage.

Note that you don't need to define a Billable metric to create a Plan. However,
if you have usage feature to charge, the price of your Billable metrics is
defined inside each Plan. Make sure to understand
[how to create a Billable metric](/guide/billable-metrics/create-billable-metrics) first.

## Plan structure[](#plan-structure "Direct link to heading")

A Plan defines the features your customers have access to, the prices paid to
access them and the invoicing cadence. In order to invoice a Customer with Lago,
you must assign a Plan to a customer.

**But first, let's define the structure of a Plan:**

<Tabs>
  <Tab title="Dashboard">
    1.  [The Plan basic informations](#plan-structure)
        *   A Plan `name`
        *   A Plan `code`
        *   A Plan `description`
    2.  [The Plan model](/guide/plans/plan-model)
        *   A Plan `interval`
        *   A Plan base `amount` with the `currency`
        *   Boolean to define if the Plan is paid **in advance** or **in arrears**
        *   A Plan `trial period` in days
        *   Taxes applied to this plan
    3.  [The additional charges](/guide/plans/charges) for this Plan (any Billable metrics
        that have been created)
        *   A Charge `model`
        *   A Charge `amount` and its `currency` (automatically inherited from the
            currency of the Plan)
        *   A Charge spending minimum
        *   Boolean to define if the Charge is paid **in advance** or **in arrears**
        *   Taxes applied to this charge (overriding the one defined on the plan)
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Premium Plan Example
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/plans" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
         "plan": {
            "name": "Premium",
            "code": "premium",
            "interval": "monthly",
            "description": "Premium plan for SMB customers",
            "amount_cents": 50000,
            "amount_currency": "USD",
            "trial_period": 3.0,
            "pay_in_advance": true,
            "bill_charges_monthly": true,
            "tax_codes": ["french_standard_vat"],
            "charges": [
               {
               "billable_metric_id": "__BILLABLE_METRIC_ID__",
               "charge_model": "graduated",
               "pay_in_advance": false,
               "invoiceable": true,
               "min_amount_cents": 0,
               "tax_codes": ["french_standard_vat"],
               "properties": {
                  "graduated_ranges": [
                     {
                        "to_value": 10,
                        "from_value": 0,
                        "flat_amount": "0",
                        "per_unit_amount": "0.001"
                     },
                     {
                        "to_value": null,
                        "from_value": 11,
                        "flat_amount": "0",
                        "per_unit_amount": "0.0005"
                     }
                  ]
               }
            }
            ]
         }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Editing Plans[](#editing-plans "Direct link to heading")

Plans can be fully edited as long as they are not linked to a customer (i.e., no active [subscriptions](/guide/subscriptions/assign-plan)). Once a plan is assigned to a customer, you can modify subscription prices, add or remove charges, and adjust them. However, other settings—such as the “plan interval,” “pay in advance” options, and pro-rated charges—become fixed and cannot be edited once assigned to a customer.

Any edits to a plan will instantly impact all subscriptions linked to it.

Please note: If this plan is linked to overridden subscriptions, you can choose to cascade or not these changes to these overridden subscriptions.
When updating a plan via the API, use the `cascade_updates: true` property to ensure that overridden subscriptions are impacted by the changes.

To update plans that are already linked to customers, you will need to either remove all active subscriptions or create a new plan.

To update a specific charge in a plan, the charge must first be removed, then re-added with the updated details.

## Deleting Plans[](#deleting-plans "Direct link to heading")

Plans can be deleted regardless of whether they are linked to a subscription.

Deleting a plan that is linked to a subscription will automatically terminate the subscription, and invoices will be generated.


# Plan model

The plan model defines when and how much a customer is charged.

## Plan interval[](#plan-interval "Direct link to heading")

The plan interval corresponds to the billing period and defines when invoices
are generated. In most cases, the [charges](/guide/plans/charges) are also calculated
according to the plan interval.

There are several plan intervals:

1.  **Weekly**: subscription fees and charges are billed on a weekly basis
    (Monday to Sunday);
2.  **Monthly**: subscription fees and charges are billed on a monthly basis;
3.  **Quarterly**: subscription fees and charges are billed on a quarterly basis (every 3 months); and
4.  **Yearly**: subscription fees are billed on a yearly basis and charges can be
    billed monthly or annually.

## The base charge amount and its currency[](#the-base-charge-amount-and-its-currency "Direct link to heading")

You need to define a **base amount** for each plan (i.e. the subscription fee).
This amount is what the customer will pay by subscribing to the plan regardless
of their consumption.

This base charge `amount` is recurring, and billed at the end of each billing
interval.

## Pay in advance or in arrears[](#pay-in-advance-or-in-arrears "Direct link to heading")

With Lago, you can define if the base charge of the Plan is paid **in advance**
or **in arrears**.

*   If the toggle is `off` (boolean set to FALSE), the Plan is paid for the past
    period (in arrears).
*   If the toggle is `on` (boolean set to TRUE), the Plan is paid upfront (in
    advance) for the period.

<Note>
  Note that this toggle only affects the base amount of the Plan. Additional
  charges for per-usage Billable metrics **are always paid in arrears because
  they are linked to a past consumption of your customers.**
</Note>

## The trial period (optional)[](#the-trial-period-optional "Direct link to heading")

You can decide to apply a `Trial period` for a Plan. This means your customers
can test the Plan without being charged for a certain number of days. This is
optional and if the value is null, the Plan holds 0 day of trial.

Note that the trial period **can only be specified in days**. A pro-rata is
applied to the Plan regarding the number of days offered.

<Warning>
  A trial period can only be applied to the first subscribed Plan. In case of an
  upgrade or downgrade, the trial period of the new Plan **is not applied**.
</Warning>

<Warning>
  The trial period is only applied to the subscription fee.
</Warning>

Any events received during the trial period will be taken into account at the end
of the billing cycle. Pay-in-advance charges will be invoiced and collected immediately
after an event is received.

If you want maximum flexibility, you can define two different Plans: one for the
free trial and one regular plan. A new customer starts on the free plan, and you
can configure the regular plan to start after the trial period. The free plan
subscription will automatically be terminated when the regular plan starts.

## Taxes applied on plans or charges

You have the option to store taxes either at a Plan level or for specific charges.
This choice entails that whenever you apply this plan to a customer without taxes,
invoice fees will inherit the taxes defined in the corresponding plan.

<Info>
  It's important to acknowledge that taxes applied to a plan will influence the charges,
  unless the taxes are explicitly defined for the individual charge.
</Info>

## Pro-ratas based on subscription date[](#pro-ratas-based-on-subscription-date "Direct link to heading")

Obviously, we know that your customers don't necessarily sign up for a Plan at
the very begining of each month (or each year). This is why Lago automatically
applies a pro-rata for the first and the last subscription period of a Plan.

Here is an example: A `Customer X` signs up for the Plan `Start` (base amount of
10€, with no trial period) on April 15, 2022.

*   If the Plan is defined to be `paid in arrears`, this Customer will be charged
    5€ for the first month at the end of the period (May 1, 2022).
*   If the Plan is defined to be `paid in advance`, this Customer is charged 5€
    straight away for the first month (April 15, 2022).

<Note>
  Note that pro-ratas can also be applied in case of **upgrades or downgrades**.
</Note>


# Progressive billing

Progressive billing, also known as threshold billing, automatically triggers an invoice when a customer's cumulative usage reaches predefined thresholds. This method ensures that customers cannot exceed certain usage limits without ensuring payment is received, reducing the risk of unpaid services or fraud.

<Info>
  **PREMIUM ADD-ON** ✨

  This progressive billing feature is available upon request only. Please **[contact us](mailto:hello@getlago.com)** to get access to this premium feature.
</Info>

## Lifetime usage

In the context of progressive billing, thresholds and invoicing behavior are **determined by the lifetime usage of a subscription**.
This approach means that Lago continuously tracks and aggregates **the total usage across all billing periods**.
By considering this cumulative usage, Lago can accurately assess whether a customer has reached predefined thresholds.

When the lifime usage reaches a specific threshold, Lago automatically triggers the invoicing process, ensuring that usage is invoiced promptly before it exceeds the specified limits. This mechanism helps prevent overuse of services without corresponding invoice and payment, offering a safeguard against potential revenue leakage.
It's important to note that lifetime usage is persistent across periods, meaning that even if a customer's usage fluctuates, Lago will account for the entire history to determine if and when an invoice should be issued.

<Info>
  The lifetime usage is calculated based on the usage amount before taxes.
</Info>

## Setting up thresholds

<Frame caption="Setting up thresholds">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/progressive-billing-setting-up-thresholds.png" />
</Frame>

For the progressive billing feature, you can configure two types of thresholds: Step-Based Thresholds and Recurring Thresholds.

### Step-based thresholds

<Tabs>
  <Tab title="Dashboard">
    For Step-Based Thresholds, invoices are generated when the lifetime usage of a subscription reaches a defined threshold.
    You can set an unlimited number of thresholds, each with a specific amount and a unique name.

    To add progressive billing Step-Based Thresholds from the UI:

    1.  Navigate to the desired plan;
    2.  Access the Advanced Settings;
    3.  Locate the Progressive Billing section; and
    4.  Add your thresholds.

    <Frame caption="Defining step-based thresholds">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/progressive-billing-step-thresholds.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```json Add progressive billing thresholds {14-27}
      {
          "plan": {
              "name": "Premium",
              "invoice_display_name": null,
              "created_at": "2024-08-26T14:23:53Z",
              "code": "premium",
              "interval": "monthly",
              "description": "",
              "amount_cents": 10000,
              "amount_currency": "USD",
              "trial_period": 0.0,
              "pay_in_advance": true,
              "charges": [...],
              "usage_thresholds": [
                  {
                      "amount_cents": 500,
                      "threshold_display_name": "Step 1 "
                  },
                  {
                      "amount_cents": 5000,
                      "threshold_display_name": "Step 2"
                  },
                  {
                      "amount_cents": 10000,
                      "threshold_display_name": "Step 3"
                  }
              ]
          }
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

In the above example, Lago will issue an invoice when the specified threshold is met:

*   `Invoice #1`: When the lifetime usage reaches \$5;
*   `Invoice #2`: When the lifetime usage reaches \$20;
*   `Invoice #3`: When the lifetime usage reaches \$50;
*   `Invoice #4`: When the lifetime usage reaches \$100;
*   `Invoice #5`: When the lifetime usage reaches \$1,000;
*   Then, resume to 'end of the month' billing.

### Recurring threshold

<Tabs>
  <Tab title="Dashboard">
    In addition to Step-Based Thresholds, you can also set up a Recurring Threshold. This threshold determines what happens after the final step-based threshold is reached.
    If a recurring threshold is defined, Lago will continue to issue invoices each time the lifetime usage increases by the specified amount.
    For example, as shown in the image below, after the last threshold, Lago will automatically bill \$100 each time the lifetime usage increments by that amount.

    To add a recurring threshold from the UI:

    1.  Navigate to the desired plan;
    2.  Access the Advanced Settings;
    3.  Locate the Progressive Billing section;
    4.  Toggle the 'Recurring' switch; and
    5.  Enter a name and define the recurring threshold amount.

    <Frame caption="Defining a recurring threshold">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/progressive-billing-recurring-threshold.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```json Add a recurring billing threshold
      {
          "plan": {
              "name": "Premium",
              "invoice_display_name": null,
              "created_at": "2024-08-26T14:23:53Z",
              "code": "premium",
              "interval": "monthly",
              "description": "",
              "amount_cents": 10000,
              "amount_currency": "USD",
              "trial_period": 0.0,
              "pay_in_advance": true,
              "charges": [...],
              "usage_thresholds": [
                  {
                      "amount_cents": 500,
                      "threshold_display_name": "Step 1 "
                  },
                  {
                      "amount_cents": 5000,
                      "threshold_display_name": "Step 2"
                  },
                  {
                      "amount_cents": 10000,
                      "threshold_display_name": "Step 3"
                  },
                  {
                  "amount_cents": 5000,
                  "threshold_display_name": "Bill every 50 dollars",
                  "recurring": true
                  }
              ]
          }
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Invoicing behaviors

For our progressive billing feature, invoices are generated whenever a threshold is crossed, regardless of when it occurs within a billing period.
However, there are a few specific behaviors and edge cases related to this feature that are important to consider.

<Frame caption="Progressive billing invoice behavior">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/progressive-billing-invoice-behavior.png" />
</Frame>

### Invoicing during job execution

It's important to note that **threshold billing occurs when our progressive billing job runs** (every 5 minutes by default, though this interval can be adjusted on a case-by-case basis).
This means that Lago does not trigger the invoice immediately when the threshold is crossed but rather at a predefined interval.

As a result, Lago will invoice the total usage at the time the job runs, **which may slightly exceed the threshold**.
For instance, if your billing threshold is \$10 but the job runs when the customer's current usage is \$12, Lago will invoice for the full \$12.

### Charges included in the calculation

**Only charges billed in arrears (recurring or metered) are included in the lifetime usage calculation for progressive billing invoices**.
This means any charges paid in advance are excluded from this progressive billing feature.

### Excluding already billed usage

When a customer crosses a threshold for a specific subscription, Lago will invoice the total usage for the current period,
ensuring that any 'previously billed usage' is excluded.

This approach provides customers with a clear view of their current consumption while preventing them from being charged again
for usage already invoiced under previous thresholds.

It's important to note that the invoice template (as shown below) includes the following details:

*   The total usage for the current period;
*   An adjustment that excludes previously billed usage; and
*   A footer that provides context, explaining the reason for the invoice, including lifetime usage and the threshold that was crossed.

<Frame caption="Progressive billing invoice detail">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/plans/images/progressive-billing-invoice-detail.png" />
</Frame>

### Grace period edge cases

It's important to note that **progressive billing invoices are not subject to a grace period** and, therefore, cannot be in a `draft` status.
The reason for this is that draft invoices are not `finalized`, and progressive billing calculations are based solely on `finalized` invoices. Including draft invoices in these calculations would significantly alter the accuracy of the progressive billing process.

### Applying discounts

Progressive billing invoices will automatically apply any available discounts, including coupons, prepaid credits, or credit notes.

### Overriding subscription thresholds

To provide maximum flexibility with the progressive billing feature, you can **override the default plan's thresholds for a specific subscription**.
This allows a particular subscription to have its own customized thresholds. You can add or remove thresholds as needed, or even disable the progressive billing feature entirely for a specific subscription.

### Modifying thresholds

You can edit, add, or remove progressive billing thresholds—or even disable this feature—at any time for a plan or subscription.
This flexibility allows you to adjust thresholds to meet your customer's needs without needing to rebuild everything from scratch.

### Being notified

Since progressive billing invoices can be triggered at any time during a billing period, it's crucial to stay informed when a customer crosses a threshold.
Lago sends a [webhook notification](/api-reference/webhooks/messages#subscription-usage-threshold-reached), `subscription.usage_threshold_reached`, providing details about the subscription and the specific threshold that was exceeded.


# API Keys



## Reveal an API Key

By accessing the **Developers > API Keys** section, you can click the **Reveal** button to display an API key of your organization.
For security reasons, the key can only be copied when it is visible.

<Frame caption="Reveal your API keys">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/security/images/reveal-api-key.png" />
</Frame>

## API Key "Last Used" Field

For security purposes, a **Last Used** field displays the last time this API key was accessed. This serves as a helpful indicator to determine if the key is still actively in use.

## Rotate an API Key

By accessing the **Developers > API Keys** section, you can click the **Roll API Key** button to generate a new API key.

When an API key is rotated, all organization admins receive an email notification about the change.
Expired keys are removed from the UI and become unusable.


# RBAC - Role Base Access Control

Define user roles & permissions in Lago.

## Admin role

Admins wield full control over Lago, managing billable metrics, plans, customers, subscriptions, settings or financial analysis.
Typically, developers with admin roles handle all critical billing operations. By default, the account creator is assigned the Admin role.

<Info>
  Only admins can invite new members and assign roles. Your account must always
  have at least one admin.
</Info>

## Account manager role

The Account manager role suits Sales or Customer Success Managers, enabling them to carry out billing tasks for customers.
Account Managers can assign subscriptions, coupons, add-ons, and override prices but are not permitted to modify metrics or plans.

## Finance & analyst role

The Finance & analyst role is view-only, restricted from creating or editing metrics and plans, or assigning core billing actions such as coupons,
subscriptions. It's ideal for analyzing financial data, reviewing invoices, and issuing credit notes as necessary.

## Roles and permissions

| category          | name                  | description                                     | admin | manager | finance |
| ----------------- | --------------------- | ----------------------------------------------- | ----- | ------- | ------- |
| Analytics         | view                  | Access the Analytics Section                    | ✅     | ❌       | ✅       |
| Billable Metrics  | view                  | Access Billable Metrics Section                 | ✅     | ❌       | ❌       |
| Billable Metrics  | create                | Create a Billable Metric                        | ✅     | ❌       | ❌       |
| Billable Metrics  | update                | Update a Billable Metric                        | ✅     | ❌       | ❌       |
| Billable Metrics  | delete                | Delete a Billable Metric                        | ✅     | ❌       | ❌       |
| Plans             | view                  | Access Plans Section                            | ✅     | ✅       | ✅       |
| Plans             | create                | Create a New Plan                               | ✅     | ❌       | ❌       |
| Plans             | update                | Update a Plan                                   | ✅     | ❌       | ❌       |
| Plans             | delete                | Delete a Plan                                   | ✅     | ❌       | ❌       |
| Plans             | create                | Duplicate a Plan                                | ✅     | ❌       | ❌       |
| Addons            | view                  | Access Add-ons Section                          | ✅     | ✅       | ✅       |
| Addons            | create                | Create a New Add-on                             | ✅     | ❌       | ❌       |
| Addons            | update                | Update an Add-on                                | ✅     | ❌       | ❌       |
| Addons            | delete                | Delete an Add-on                                | ✅     | ❌       | ❌       |
| Coupons           | view                  | Access Coupons Section                          | ✅     | ✅       | ✅       |
| Coupons           | create                | Create a New Coupon                             | ✅     | ❌       | ❌       |
| Coupons           | update                | Update a Coupon                                 | ✅     | ❌       | ❌       |
| Coupons           | delete                | Delete a Coupon                                 | ✅     | ❌       | ❌       |
| Coupons           | update                | Terminate a Coupon                              | ✅     | ❌       | ❌       |
| Coupons           | attach                | Apply a Coupon                                  | ✅     | ✅       | ❌       |
| Coupons           | detach                | Remove a Coupon                                 | ✅     | ✅       | ❌       |
| Customers         | view                  | Access Customers Section                        | ✅     | ✅       | ✅       |
| Customers         | view                  | Access Customers Details                        | ✅     | ✅       | ✅       |
| Customers         | create                | Create a New Customer                           | ✅     | ✅       | ❌       |
| Customers         | update                | Update a Customer                               | ✅     | ✅       | ❌       |
| Customers         | delete                | Delete a Customer                               | ✅     | ✅       | ❌       |
| Subscriptions     | view                  | Access subscriptions                            | ✅     | ✅       | ✅       |
| Subscriptions     | create                | Assign a New Plan                               | ✅     | ✅       | ❌       |
| Subscriptions     | update                | Edit subscription                               | ✅     | ✅       | ❌       |
| Subscriptions     | update                | Upgrade/downgrade                               | ✅     | ✅       | ❌       |
| Subscriptions     | delete                | Delete subscription                             | ✅     | ✅       | ❌       |
| Wallets           | create                | Create a Wallet                                 | ✅     | ✅       | ❌       |
| Wallets           | update                | Edit a Wallet                                   | ✅     | ✅       | ❌       |
| Wallets           | top\_up               | Top-up a Wallet                                 | ✅     | ✅       | ❌       |
| Wallets           | terminate             | Terminate a Wallet                              | ✅     | ✅       | ❌       |
| Invoices          | view                  | Access Invoice List                             | ✅     | ✅       | ✅       |
| Invoices          | view                  | Download an Invoice                             | ✅     | ✅       | ✅       |
| Invoices          | send                  | Resend an Invoice                               | ✅     | ✅       | ✅       |
| Invoices          | update                | Update Payment Status                           | ✅     | ✅       | ✅       |
| Invoices          | void                  | Void an Invoice                                 | ✅     | ✅       | ✅       |
| Invoices          | create                | One-off Invoices                                | ✅     | ✅       | ✅       |
| Invoices          | update                | Edit a Draft Invoice                            | ✅     | ✅       | ✅       |
| Invoices          | update                | Refresh a Draft invoice                         | ✅     | ✅       | ✅       |
| Invoices          | update                | Finalize a Draft invoice                        | ✅     | ✅       | ✅       |
| Draft Invoices    | update                | Edit a Draft Invoice                            | ✅     | ✅       | ✅       |
| Draft Invoices    | update                | Refresh a Draft invoice                         | ✅     | ✅       | ✅       |
| Draft Invoices    | update                | Finalize a Draft invoice                        | ✅     | ✅       | ✅       |
| Credit Notes      | view                  | Access Credit Notes List                        | ✅     | ✅       | ✅       |
| Credit Notes      | create                | Create a Credit Note                            | ✅     | ✅       | ✅       |
| Credit Notes      | view                  | Download a Credit Note PDF                      | ✅     | ✅       | ✅       |
| Credit Notes      | update                | Don't know what this is but there is a mutation | ✅     | ✅       | ✅       |
| Credit Notes      | void                  | Void a Credit Note                              | ✅     | ✅       | ✅       |
| Customer Settings | view                  | Access Customer’s Settings                      | ✅     | ✅       | ✅       |
| Customer Settings | update:tax\_rates     | Add Tax Rates                                   | ✅     | ✅       | ✅       |
| Customer Settings | update:payment\_terms | Edit Net Payment Terms                          | ✅     | ✅       | ✅       |
| Customer Settings | update:grace\_period  | Edit Grace Period                               | ✅     | ✅       | ✅       |
| Customer Settings | update:lang           | Edit Document Language                          | ✅     | ✅       | ✅       |
| Developers        | manage                | Access Developers Section                       | ✅     | ❌       | ❌       |
| Developers        | keys:manage           | Access API Keys                                 | ✅     | ❌       | ❌       |
| Developers        | manage                | Access Events List                              | ✅     | ❌       | ❌       |
| Developers        | manage                | Access Webhooks                                 | ✅     | ❌       | ❌       |
| Organization      | view                  | Access Organization Settings                    | ✅     | ❌       | ✅       |
| Organization      | update                | Edit Organization Information                   | ✅     | ❌       | ✅       |
| Organization      | invoices:view         | Access Invoices’ Global Information             | ✅     | ❌       | ✅       |
| Organization      | invoices:update       | Edit Invoices’ Global Information               | ✅     | ❌       | ✅       |
| Organization      | taxes:view            | Access Global Taxes Information                 | ✅     | ❌       | ❌       |
| Organization      | taxes:update          | Edit Global Taxes Information                   | ✅     | ❌       | ❌       |
| Organization      | emails:view           | Access Emails Settings                          | ✅     | ❌       | ❌       |
| Organization      | emails:update         | Edit Emails Settings                            | ✅     | ❌       | ❌       |
| Organization      | integrations:view     | Access Integrations Section                     | ✅     | ❌       | ✅       |
| Organization      | integrations:create   | Add an Integration                              | ✅     | ❌       | ✅       |
| Organization      | integrations:update   | Edit an Integration                             | ✅     | ❌       | ✅       |
| Organization      | integrations:delete   | Delete an Integration                           | ✅     | ❌       | ✅       |
| Organization      | members:view          | Access Members Section                          | ✅     | ❌       | ❌       |
| Organization      | members:create        | Add a Member and Choose Its Role                | ✅     | ❌       | ❌       |
| Organization      | members:update        | Edit a Member and Its Role                      | ✅     | ❌       | ❌       |
| Organization      | members:delete        | Delete a Member                                 | ✅     | ❌       | ❌       |


# SOC 2 Type 2

Keeping your data secure.

Lago has achieved SOC 2 Type 2 compliance for its fully hosted version, which certifies the effectiveness of our operating and security controls.
Please contact [hello@getlago.com](mailto:hello@getlago.com) to request the full report. Please note that the self-hosted version is compliant by default, as you own the data and the infrastructure.

## Data Security

Lago encrypts data at rest and in transit for all of our customers. We use Amazon Web Service’s Key Management System (KMS) to manage encryption keys for maximum security, in line with industry best practices.

## Application Security

Lago also uses Dependabot, a high-quality analysis tooling provided by GitHub Advanced Security, to secure our product at every step of the development process.

## Infrastructure Security

Lago uses Amazon Web Services to host our application. We make use of the security products embedded within the AWS ecosystem, including KMS and GuardDuty.
In addition, we deploy our application using Kubernetes containers run on AWS managed services, meaning we typically do not manage servers or EC2 instances in production.

If you have further questions about security, please refer to [this page](https://www.getlago.com/company/security)


# Single Sign-On (SSO)



## Google SSO

Lago integrates with Google Single Sign-On (Google SSO), enabling your team to access Lago using their existing Google credentials.
This seamless integration allows team members to log in with their corporate Gmail accounts, eliminating the need for additional usernames and passwords.
This streamlines the login process and enhances security by leveraging Google's authentication infrastructure.

## Okta SSO

<Info>
  **PREMIUM ADD-ON** ✨

  This add-on is available on demand only. Please **[contact us](mailto:hello@getlago.com)** to get access to this premium add-on.
</Info>

Lago integrates with Okta Single Sign-On (Okta SSO), enabling your team to access Lago using their existing Okta credentials.

### Connect Lago to Okta

To connect Lago to Okta, please follow these steps:

1.  Go to your Lago Settings view.
2.  Access the Authentication section.
3.  Configure Okta by adding the requested information:
4.  Domain name | Okta public key | Okta private key | Okta organization name

<Frame caption="Illustration of the Okta SSO connection">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/security/images/okta-connection.png" />
</Frame>

### Log in to Lago or join an existing organization

Once this integration is switched on, it allows team members to log in or join an existing organization with their corporate Okta accounts, eliminating the need for additional usernames and passwords. This streamlines the login process and enhances security by leveraging Okta’s authentication infrastructure.

### Edit or delete Okta's connection

Once this integration is switched on, you can edit the connection information or delete it. Please note that once deleted, you won't be able to access Lago via Okta SSO. Use the Forgot password feature to regain access to your account.


# Useful commands

Useful commands for self-hosted users.

Below is a compilation of essential commands tailored for open-source enthusiasts, primarily designed for managing invoicing tasks,
whether for immediate processing or scheduling.

These commands are designed to execute a Rails console (rails c) within a Docker container named api, which is managed by Docker Compose.

```
docker-compose exec api rails c
```

## Dry-run invoice in the future

Use this to simulate a dry run invoice for a future date. Ensure to specify the correct subscription `external_id` and the targeted invoice issuance date.

```ruby
# In the rails Console
subscription = Subscription.find_by(external_id: 'YOUR_SUB_EXTERNAL_ID')
date = DateTime.parse('2024-10-01').to_i

BillSubscriptionJob.perform_later([subscription], date)
```

## Issue invoice immediately

Use this to issue an invoice immmediately. Ensure to specify the correct subscription `external_id` and the current date.

```ruby
# In the rails Console
subscription = Subscription.find_by(external_id: 'YOUR_SUB_EXTERNAL_ID')
timestamp = DateTime.parse('2024-04-01').to_i
BillSubscriptionJob.perform_now([subscription], timestamp, invoicing_reason: :subscription_periodic)
```

## Remove cache for a subscription

Use this to remove the cache on a specific subscription.

```ruby
# In the rails Console
Subscriptions::ChargeCacheService.expire_for_subscription(Subscription.find('YOUR_SUB_EXTERNAL_ID'))
```

To remove the cache for all subscriptions, you can alternatively use this command:

```ruby
# In the rails Console
Subscription.find_each {|s| Subscriptions::ChargeCacheService.expire_for_subscription(s) }
```


# Docker

Docker is the easiest way to get started with the self-hosted version of Lago.

## Requirements[](#requirements "Direct link to heading")

1.  Install [Docker](https://docs.docker.com/get-docker/) on your machine;
2.  Make sure [Docker Compose](https://docs.docker.com/compose/install/) is
    installed and available (it should be the case if you have chosen to install
    Docker via Docker Desktop); and
3.  Make sure
    [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) is
    installed on your machine.

## Run the app[](#run-the-app "Direct link to heading")

To start using Lago, run the following commands in a shell:

```shell
# Get the code
git clone https://github.com/getlago/lago.git

# Go to Lago folder
cd lago

# Set up environment configuration
echo "LAGO_RSA_PRIVATE_KEY=\"`openssl genrsa 2048 | base64`\"" >> .env
source .env

# Start the api
docker compose up -d api

# Create the database
docker compose exec api rails db:create
docker compose exec api rails db:migrate

# Start all other components
docker compose up

```

You can now open your browser and go to [http://localhost](http://localhost) to
connect to the application. Just after
[signing up](#signing-up), Lago's API is exposed
at [http://localhost:3000](http://localhost:3000).

## Signing up[](#signing-up "Direct link to heading")

It's mandatory to create your organization by signing up to Lago. This
organization is the core object of your biller as it's used to invoice your
customers.

1.  Write down your `organization name`;
2.  Use the main billing `email` of your company; and
3.  Define the admin `password` for this email.

You will be able to **invite other email addresses within the application**. If
you already have an account, you can also log in. Once you are able to access
the app, you can retrieve your API key.

## Find your API Key[](#find-your-api-key "Direct link to heading")

Your API Key can be found directly in the UI:

1.  Access the **Developer** section from the sidebar;
2.  The first tab of this section is related to your **API keys**; and
3.  Click the **Copy** button to copy it to clipboard.

## Configuration[](#configuration "Direct link to heading")

### Version[](#version "Direct link to heading")

Docker images are always updated to the last stable version in the
`docker-compose.yml` file. You can use a different tag if needed by checking the
[releases list](https://github.com/getlago/lago/releases).

<Warning>
  We recommend to avoid the usage of `latest` tag, you should use the last
  tagged version, you can track what are the last version on Dockerhub
</Warning>

*   lago-api :
    [https://hub.docker.com/repository/docker/getlago/api](https://hub.docker.com/repository/docker/getlago/api)
*   lago-front :
    [https://hub.docker.com/repository/docker/getlago/front](https://hub.docker.com/repository/docker/getlago/front)

### Environment variables[](#environment-variables "Direct link to heading")

Lago uses the following environment variables to configure the components of the
application. You can override them to customise your setup.

| Variable                              | Default value                                  | Description                                                                                                                                                      |
| ------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POSTGRES_HOST`                       | db                                             | (*With Docker compose*) Host name of the postgres server                                                                                                         |
| `POSTGRES_DB`                         | lago                                           | (*With Docker compose*) Name of the postgres database                                                                                                            |
| `POSTGRES_USER`                       | lago                                           | (*With Docker compose*) Database user for postgres connection                                                                                                    |
| `POSTGRES_PASSWORD`                   | changeme                                       | (*With Docker compose*) Database password for postgres connection                                                                                                |
| `POSTGRES_PORT`                       | 5432                                           | (*With Docker compose*) Port the postgres database listens to                                                                                                    |
| `POSTGRES_SCHEMA`                     | public                                         | Name of the postgres schema                                                                                                                                      |
| `DATABASE_URL`                        |                                                | (*Without docker compose*) Full url to the postgres server                                                                                                       |
| `DATABASE_POOL`                       | 10                                             | Max number of connection opened to the postgres database per api, worker and clock instances                                                                     |
| `DATABASE_PREPARED_STATEMENTS`        | true                                           | Enable or disable prepared statements in the postgres database                                                                                                   |
| `REDIS_HOST`                          | redis                                          | Host name of the redis server                                                                                                                                    |
| `REDIS_PORT`                          | 6379                                           | Port the redis database listens to                                                                                                                               |
| `REDIS_PASSWORD`                      |                                                | Password of the redis server                                                                                                                                     |
| `LAGO_REDIS_CACHE_HOST`               | redis                                          | Host name of the redis cache server                                                                                                                              |
| `LAGO_REDIS_CACHE_PORT`               | 6379                                           | Port the redis cache server listens to                                                                                                                           |
| `LAGO_REDIS_CACHE_PASSWORD`           |                                                | Password of the redis cache server                                                                                                                               |
| `LAGO_REDIS_CACHE_POOL_SIZE`          | 5                                              | Max number of connections in the redis cache connection pool                                                                                                     |
| `LAGO_MEMCACHE_SERVERS`               |                                                | Coma separated list of memcache servers                                                                                                                          |
| `LAGO_FRONT_URL`                      | [http://localhost](http://localhost)           | URL of the Lago front-end application.Used for CORS configuration                                                                                                |
| `FRONT_PORT`                          | 80                                             | Port the front-end application listens to                                                                                                                        |
| `LAGO_API_URL`                        | [http://localhost:3000](http://localhost:3000) | URL of the Lago back-end application                                                                                                                             |
| `API_URL`                             | [http://localhost:3000](http://localhost:3000) | URL of the Lago back-end application defined for the front image                                                                                                 |
| `API_PORT`                            | 3000                                           | Port the back-end application listens to                                                                                                                         |
| `SECRET_KEY_BASE`                     | your-secret-key-base-hex-64                    | Secret key used for session encryption                                                                                                                           |
| `SENTRY_DSN`                          |                                                | Sentry DSN key for error and performance tracking on Lago back-end                                                                                               |
| `SENTRY_DSN_FRONT`                    |                                                | Sentry DSN key for error and performance tracking on Lago front-end                                                                                              |
| `LAGO_RSA_PRIVATE_KEY`                |                                                | Private key used for webhook signatures                                                                                                                          |
| `LAGO_SIDEKIQ_WEB`                    |                                                | Activate the Sidekiq web UI, disabled by default                                                                                                                 |
| `LAGO_ENCRYPTION_PRIMARY_KEY`         | your-encryption-primary-key                    | Encryption primary key used to secure sensitive values stored in the database                                                                                    |
| `LAGO_ENCRYPTION_DETERMINISTIC_KEY`   | your-encryption-deterministic-key              | Encryption deterministic key used to secure sensitive values stored in the database                                                                              |
| `LAGO_ENCRYPTION_KEY_DERIVATION_SALT` | your-encryption-derivation-salt                | Encryption key salt used to secure sensitive values stored in the database                                                                                       |
| `LAGO_WEBHOOK_ATTEMPTS`               | 3                                              | Number of failed attempt before stopping to deliver a webhook                                                                                                    |
| `LAGO_USE_AWS_S3`                     | false                                          | Use AWS S3 for files storage                                                                                                                                     |
| `LAGO_AWS_S3_ACCESS_KEY_ID`           | azerty123456                                   | AWS Access Key id that has access to S3                                                                                                                          |
| `LAGO_AWS_S3_SECRET_ACCESS_KEY`       | azerty123456                                   | AWS Secret Access Key that has access to S3                                                                                                                      |
| `LAGO_AWS_S3_REGION`                  | us-east-1                                      | AWS S3 Region                                                                                                                                                    |
| `LAGO_AWS_S3_BUCKET`                  | bucket                                         | AWS S3 Bucket name                                                                                                                                               |
| `LAGO_AWS_S3_ENDPOINT`                |                                                | S3 compatible storage endpoint. Should be set only if you are using another storage provider than AWS S3                                                         |
| `LAGO_USE_GCS`                        | false                                          | Use Google Cloud Service Cloud Storage for file storage, ⚠️ If you want to use GCS, you have to pass the credentials json key file to the api and worker service |
| `LAGO_GCS_PROJECT`                    |                                                | GCS Project name                                                                                                                                                 |
| `LAGO_GCS_BUCKET`                     |                                                | GCS Bucket Name                                                                                                                                                  |
| `LAGO_PDF_URL`                        | [http://pdf:3000](http://pdf:3000)             | PDF Service URL on your infrastructure                                                                                                                           |
| `LAGO_DISABLE_SIGNUP`                 |                                                | Disable Sign up when running Lago in self-hosted                                                                                                                 |
| `LAGO_RAILS_STDOUT`                   | true                                           | Set to true to activate logs on containers                                                                                                                       |
| `LAGO_DISABLE_WALLET_REFRESH`         |                                                | Disable automatic refresh of wallet ongoing balance                                                                                                              |
| `GOOGLE_AUTH_CLIENT_ID`               |                                                | Client ID for Google auth Single Sign On                                                                                                                         |
| `GOOGLE_AUTH_CLIENT_SECRET`           |                                                | Client Secret for Google auth Single Sign On                                                                                                                     |

<Warning>
  We recommend that you change `POSTGRES_PASSWORD`, `SECRET_KEY_BASE`,
  `LAGO_RSA_PRIVATE_KEY`, `LAGO_ENCRYPTION_PRIMARY_KEY`,
  `LAGO_ENCRYPTION_DETERMINISTIC_KEY` and `LAGO_ENCRYPTION_KEY_DERIVATION_SALT` to
  improve the security of your Lago instance:

  *   `SECRET_KEY_BASE` can be generated using the `openssl rand -hex 64` command.
  *   `LAGO_RSA_PRIVATE_KEY` can be generated using the
      `openssl genrsa 2048 | base64` command.
  *   `LAGO_ENCRYPTION_PRIMARY_KEY`, `LAGO_ENCRYPTION_DETERMINISTIC_KEY` and
      `LAGO_ENCRYPTION_KEY_DERIVATION_SALT` can all be gerated using the
      `cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1` command.
</Warning>

### Components[](#components "Direct link to heading")

Lago uses the following containers:

| Container    | Role                                                                  |
| ------------ | --------------------------------------------------------------------- |
| `front`      | Front-end application                                                 |
| `api`        | API back-end application                                              |
| `api_worker` | Asynchronous worker for the API application                           |
| `api_clock`  | Clock worker for the API application                                  |
| `db`         | Postgres database engine used to store application data               |
| `redis`      | Redis database engine used as a queuing system for asynchronous tasks |
| `pdf`        | PDF generation powered by Gotenberg                                   |

You can also use your own database or Redis server. To do so, remove the `db`
and `redis` configurations from the `docker-compose.yml` file and update the
environment variables accordingly.

### SSL Support[](#ssl-support "Direct link to heading")

Lago Front application can be configured to support SSL certificates. You have
two options to achieve this:

*   by using a self-signed certificate
*   by using a signed certificate generated by Let's Encrypt

#### Self Signed Certificate[](#self-signed-certificate "Direct link to heading")

*   Run the script to generate the certificates

```shell
# Be sure to be in your lago folder
./extra/init-selfsigned.sh

# This should create certificates in the ./extra/ssl/ folder
```

*   Take a look at the `docker-compose.yml` file and uncomment the part related to
    the Self-Signed certificate

```yaml
volumes:
  - ./extra/nginx-selfsigned.conf:/etc/nginx/conf.d/default.conf
  - ./extra/ssl/nginx-selfsigned.crt:/etc/ssl/certs/nginx-selfsigned.crt
  - ./extra/ssl/nginx-selfsigned.key:/etc/ssl/private/nginx-selfsigned.key
  - ./extra/ssl/dhparam.pem:/etc/ssl/certs/dhparam.pem
```

*   You can now start the front application with a self signed SSL certificate
    support

```shell
docker-compose up front
```

#### Let's Encrypt Certificate[](#lets-encrypt-certificate "Direct link to heading")

*   Edit the file `extra/init-letsencrypt.sh`
    *   You must replace `lago.example` with your domain name
    *   You must enter a valid email address
*   Edit the file `extra/nginx-letsencrypt.conf`
    *   You must replace `lago.example` with your domain name
*   Uncomment the [Cerbot lines](https://github.com/getlago/lago/blob/5d08b61f4f174f445b258005854aaa18ca049266/docker-compose.yml#L124-L129) in the `docker-compose.yml` file
*   Run the following script

```shell
# Be sure to be in your lago folder
./extra/init-letsencrypt.sh

# You will be asked to provide some information
# After that you should be able to see the extra/certbot folder
```

*   Take a look at the `docker-compose.yml` file and uncomment all the parts
    related to the Let's Encrypt's support

```yaml
command:
  '/bin/sh -c ''while :; do sleep 6h & wait $${!}; nginx -s reload; done & nginx
  -g "daemon off;"'''
---
volumes:
  - ./extra/nginx-letsencrypt.conf:/etc/nginx/conf.d/default.conf
  - ./extra/certbot/conf:/etc/letsencrypt
  - ./extra/certbot/www:/var/www/certbot
```

*   You can now start the front application with the signed certificate support

```shell
docker-compose up front
```

### Storage[](#storage "Direct link to heading")

By default, Lago uses the internal storage of the container. You can customize
it by defining different environment variables.

We currently support :

*   AWS S3
*   AWS S3 Compatibles Endpoints
*   Google Cloud Service Cloud Storage

<Warning>
  If you use S3 compatibles endpoints, you should set the `LAGO_AWS_S3_REGION`
  to a default value (ei: `us-east-1`), it is required to work properly!
</Warning>

#### AWS S3[](#aws-s3 "Direct link to heading")

You have to set these variables to use AWS S3.

| Name                            | Description                             |
| ------------------------------- | --------------------------------------- |
| `LAGO_USE_AWS_S3`               | Set to "true" if you want to use AWS S3 |
| `LAGO_AWS_S3_ACCESS_KEY_ID`     | AWS S3 Credentials Access Key Id        |
| `LAGO_AWS_S3_SECRET_ACCESS_KEY` | AWS S3 Credentials Secret Access Key    |
| `LAGO_AWS_S3_REGION`            | AWS S3 Region                           |
| `LAGO_AWS_S3_BUCKET`            | AWS S3 Bucket                           |

#### AWS S3 Compatible Endpoints[](#aws-s3-compatible-endpoints "Direct link to heading")

You have to set these variables to use AWS S3 Compatible Endpoints.

| Name                            | Description                                                  |
| ------------------------------- | ------------------------------------------------------------ |
| `LAGO_USE_AWS_S3`               | Set to "true" if you want to use AWS S3 Compatible Endpoints |
| `LAGO_AWS_S3_ENDPOINT`          | AWS S3 Compatible Endpoint                                   |
| `LAGO_AWS_S3_ACCESS_KEY_ID`     | AWS S3 Credentials Access Key Id                             |
| `LAGO_AWS_S3_SECRET_ACCESS_KEY` | AWS S3 Credentials Secret Access Key                         |
| `LAGO_AWS_S3_BUCKET`            | AWS S3 Bucket                                                |
| `LAGO_AWS_S3_REGION`            | Not used but required by the AWS SDK                         |

#### Google Cloud Service Cloud Storage[](#google-cloud-service-cloud-storage "Direct link to heading")

You have to set those variables to use GCS Cloud Storage.

| Name               | Description                                        |
| ------------------ | -------------------------------------------------- |
| `LAGO_USE_GCS`     | Set to "true" if you want to use GCS Cloud Storage |
| `LAGO_GCS_PROJECT` | GCS Project name                                   |
| `LAGO_GCS_BUCKET`  | GCS Bucket name                                    |

In the `docker-compose.yml` file, you must uncomment the lines and pass the
correct GCS credentials json file.

```yaml
api:
  volumes:
    - gcs_keyfile.json:/app/gcs_keyfile.json

api-worker:
  volumes:
    - gcs_keyfile.json:/app/gcs_keyfile.json
```

### SMTP Configuration[](#smtp-configuration")

In order to use the email feature, you need to configure some environment variables.

<Warning>
  In addition to this configuration, defining an organization email in Settings > Organization is mandatory; without it, emails will not be sent.
</Warning>

| Name                 | Description                                                                      |
| -------------------- | -------------------------------------------------------------------------------- |
| `LAGO_FROM_EMAIL`    | Required to send emails (i.e: [noreply@getlago.com](mailto:noreply@getlago.com)) |
| `LAGO_SMTP_ADDRESS`  | Address of the SMTP server                                                       |
| `LAGO_SMTP_PORT`     | Port of the SMTP Server                                                          |
| `LAGO_SMTP_USERNAME` | Username of the SMTP Server                                                      |
| `LAGO_SMTP_PASSWORD` | Password of the SMTP Server                                                      |

#### Single Sign On using Google authentication[](#single-sign-on-using-google-authentication)

In order to enable Google authentication for single sign on, you have to set those variables.

| Name                        | Description                                  |
| --------------------------- | -------------------------------------------- |
| `GOOGLE_AUTH_CLIENT_ID`     | Client ID for Google auth Single Sign On     |
| `GOOGLE_AUTH_CLIENT_SECRET` | Client Secret for Google auth Single Sign On |


# Overview

Deploy Lago seamlessly on your infrastructure, compatible with both free and premium editions.

Lago provides versatile hosting options: on your local computer, a dedicated server, or in the cloud.

## Officially Supported

<CardGroup cols={2}>
  <Card title="Docker" href="./docker">
    Install Lago on your infrastructure with Docker Compose for easy deployment.
  </Card>

  <Card title="Kubernetes" href="https://github.com/getlago/lago-helm-charts">
    Utilize official Helm charts for deploying Lago on Kubernetes.
  </Card>
</CardGroup>


# Tracking & Analytics



## Why does Lago need data?[](#why-does-lago-need-data "Direct link to heading")

We decided to open-source the billing API we would have dreamt to use. As a
consequence of building a self hosted product, we are not able to easily collect
any usage metrics or insights to help us build a better product. This analytic
help us understand crucial behaviors and ship better quality to serve your
needs.

We decided to track, by default, so basic behaviors and metrics that are
important to understand the usage of Lago. We have built a minimum required
tracking plan to minimize the security impact of collecting those events. All
the metrics collected are listed in a further section. We make this as
transparent as possible, and we don't track financial information (amounts of
invoices, for instance).

The metrics are collected through the server side Ruby source from
[Segment.com](https://segment.com/docs/connections/sources/catalog/libraries/server/ruby/).

<Info>
  Lago will not collect any financial information about your customers or your
  invoices.
</Info>

## Opting out[](#opting-out "Direct link to heading")

As detailed previously, we ask you to keep as much as possible those tracked
metrics, unless you have a specific reason to opt out. Keeping the metrics
enabled is the easiest way for Lago to get feedback based on product usage.

In the case you need to remove it, we've created a very easy process to opt out.
In the environment variables, by passing the field `LAGO_DISABLE_SEGMENT` to
`true`, you prevent the entire tracking logic to run in your application.

## Detail of events collected by Lago[](#detail-of-events-collected-by-lago "Direct link to heading")

This event flow enables Lago to understand the full activation flow, from the
registration to the first invoice generated.

*   `organization_registered`: when you create your organization by signing up to Lago
*   `billable_metric_created`: whenever you create a new billable metric
*   `plan_created`: whenever you create a new plan
*   `customer_created`: whenever a customer is created in Lago
*   `subscription_created`: when a subscription is assigned to a customer
*   `coupon_created`: whenever a new coupon is created
*   `applied_coupon_created`: when a coupon is assigned to a customer
*   `add_on_created`: whenever a new add-on is created
*   `invoice_created`: when a new invoice is emitted for a specific customer
*   `payment_status_changed`: when the payment status of an invoice changes
*   `credit_note_issued`: when a new credit note is issued for a customer
*   `billable_metric_deleted`: when a billable metric is deleted
*   `plan_deleted`: when a plan is deleted
*   `customer_deleted`: when a customer account is deleted

## Detail of data collected about your organization[](#detail-of-data-collected-about-your-organization "Direct link to heading")

By default, we collect data of your organization that you used in the signup
form:

*   Your organization's **email**; and
*   Your organization's **name**.

By [opting out](#opting-out), your organization's data
won't be tracked anymore.

## Examples of collected payloads[](#examples-of-collected-payloads "Direct link to heading")

### billable\_metric\_created[](#billable%5Fmetric%5Fcreated "Direct link to heading")

```javascript
Analytics.track(
  user_id: 'membership/f37a6b2e-1e79-4710-b0e2-9e451b532461',
  event: 'billable_metric_created',
  properties: {
    aggregation_property: 'amount',
    aggregation_type: 'sum_agg',
    code: 'atm',
    description: '',
    hosting_type: 'self',
    name: 'ATM',
    organization_id: '7c868af7-201c-4ebc-9829-ca902e289e5f',
    version: DateTime.iso8601('2022-07-27T00:00:00.000Z')
  }
)
```

### customer\_created[](#customer%5Fcreated "Direct link to heading")

```javascript
Analytics.track(
  user_id: 'membership/4ad5b91f-2a42-4a58-9786-6c07fa03a3d4',
  event: 'customer_created',
  properties: {
    created_at: DateTime.iso8601('2022-08-10T09:34:37.479Z'),
    customer_id: '29a17eed-021c-485e-b3fa-93d27db31c95',
    hosting_type: 'cloud',
    organization_id: '0d173830-9017-4f57-9d11-e3e83b3e38fe',
    payment_provider: 'stripe',
    version: DateTime.iso8601('2022-08-09T00:00:00.000Z')
  }
)
```

### invoice\_created[](#invoice%5Fcreated "Direct link to heading")

```javascript
Analytics.track(
  user_id: 'membership/f37a6b2e-1e79-4710-b0e2-9e451b532461',
  event: 'invoice_created',
  properties: {
    hosting_type: 'cloud',
    invoice_id: '0e31afd2-8e15-49e1-a6fb-11895fa03c97',
    invoice_type: 'subscription',
    organization_id: 'b3e35674-c3d1-4279-8ef1-271271b6cafb',
    version: DateTime.iso8601('2022-07-27T00:00:00.000Z')
  }
)
```


# Versions update



Lago's speed is rapidly increasing—remarkably fast. Billing updates occur frequently, precisely every 1 or 2 weeks. Over the course of a year, we've completed over 70 releases, culminating in approximately 30 comprehensive product updates. Maintaining the currency of your self-hosted instance is paramount for optimal billing engine functionality and alignment with the newest features. Below is a guide to achieve this seamlessly, all within the span of just 5 seconds.

<Frame type="glass">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/updates.png" />
</Frame>

## Why update your Lago self-hosted instance?

### Bug fixes and security enhancements

Updating your Lago open source instance serves a key purpose: resolving bugs and enhancing security protocols.
Just like any software, glitches may emerge, impacting operations and even jeopardizing security.
This is particularly vital in intricate tasks like metering, billing calculations, tax application, and managing financial statements.
By keeping up with updates, you guarantee your instance remains unaffected by recognized problems and vulnerabilities.
This proactive approach maintains a resilient and secure operational landscape for your company.

### Access to new features

Lago consistently evolves to meet the needs of its users. Each update introduces a host of new features aimed at enhancing the user
experience and expanding the capabilities of the platform. Some notable new features that updates might bring include core billing
enhancements, tax-related features, and additional settings options. By updating regularly, you can take advantage of these features and
streamline your workflows.

## Determining update frequency

The frequency of updates varies based on the development cycle of Lago. Generally, updates are released approximately once a week.
Keeping an eye on the [release notes](https://github.com/getlago/lago/releases) provided by the Lago team will give you insight into when updates are available and what changes they
entail. Regularly monitoring these release notes will allow you to stay informed and plan your updates accordingly. Billing updates occur
frequently, precisely every 1 or 2 weeks. Over the course of a year, we've completed over 70 releases, culminating in approximately
30 comprehensive [product updates](https://www.getlago.com/changelog).

## A seamless update process

Updating your Lago open source instance doesn't have to be a daunting task. With a clear procedure in place, you can ensure
a smooth transition to the latest version. Here's a step-by-step guide to help you navigate the update process:

### 1. Access your instance repository

Navigate to the repository where your Lago open source instance is stored. This is typically where you initially cloned or
downloaded the instance.

### 2. Pull the latest code

In the repository directory, execute the following command to pull the latest code from the remote repository:

```bash
git pull
```

This command fetches the most recent changes from the remote repository and merges them into your local instance.

### 3. Restart the updated instance

Once the code is up-to-date, navigate to the directory containing your Docker Compose file.
Execute the following command to start the updated instance:

```bash
docker compose up
```

This command will rebuild and launch your Lago instance with the latest changes.

### 4. Testing new features

After the instance restarts, you can now test our new features and give feedback to the team.

## Addressing concerns about breaking changes

It's natural to be cautious about updates, especially if you fear breaking changes that might disrupt your operations. However, the Lago team understands this concern and takes proactive measures to ensure a smooth update experience. By applying careful consideration to database and UI migrations, Lago mitigates the risk of breaking your application during updates. This thoughtful approach ensures that your workflows and user interfaces remain consistent even after applying the latest updates.

In conclusion, updating your Lago open source instance is a proactive step toward maintaining a secure and feature-rich environment for your operations. By staying current with bug fixes, security enhancements, and new features, you can harness the full potential of the platform. With a well-defined update process and the Lago team's commitment to stability, you can confidently keep your instance up-to-date, ensuring a seamless and productive experience.


# Assign a plan to a customer

A subscription is created when a plan is assigned to a customer.  You can assign a plan to a customer at any time (i.e. when the customer record is created or later on).

<Tabs>
  <Tab title="Dashboard">
    To assign a plan to a customer through the user interface:

    1.  Access the **"Customers"** section via the side menu;
    2.  Select a customer from the list;
    3.  In the **"Overview"** tab, click **"Add a plan"** on the right;
    4.  Select a plan (that you can overwrite if needed - [see below](#overwriting-a-plan));
    5.  Give a name to the subscription (name that will be displayed on the invoice - optional);
    6.  Give an id to the subscription (define your own subscription identifier - optional);
    7.  Set a subscription start date (start date of the subscription - [see below](#subscription-start-date));
    8.  Set a subscription end date (start date of the subscription - [see below](#subscription-end-date) - optional);
    9.  Choose whether the subscription should be renewed at the beginning of the period or on its anniversary date (see [below](#billing-cycles)); and
    10. Click **"Add plan"** to confirm;
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Assign a plan to a customer
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/subscriptions" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "subscription": {
          "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "plan_code": "premium",
          "external_id": "my_sub_12345789",
          "name": "Repository 1",
          "subscription_at": "2022-08-08T00:00:00Z",
          "billing_time": "anniversary"
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

When a subscription is active, Lago will automatically generate invoices for the customer according to the [plan model](/guide/plans/plan-model). It will also start monitoring the customer's consumption, which means that you can start pushing [events](/guide/events/ingesting-usage) related to this subscription.

<Info>
  The subscription date displayed in the app is based on the organization's timezone.
</Info>

## Billing cycles

Optimize billing for your customers by assigning subscriptions based on either calendar dates or anniversary dates (the day they signed up).

<Tabs>
  <Tab title="Calendar billing period">
    By default, subscriptions are based on **calendar periods**. Therefore, if you assign a monthly plan to a customer on July 14th:

    *   The first invoice will be generated for the period July 14th to July 31st;
    *   The next invoice will be generated for the period August 1st to August 31st; and
    *   All future invoices will be generated for full calendar months.

    When a subscription starts during the month, the subscription fee will be calculated on a **pro rata basis** according to the number of days.

    Consider the following example:

    > Your customer signs up for the Premium plan, \$50 monthly, on August 10th. There are 22 days left until the end of the month, including August 10th. Therefore, the subscription fee for August is:
    > **22 days x \$50 / 31 days = \$35.48**

    <Frame caption="Calendar billing cadence">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/subscriptions/images/calendar-date-227bf60245e9d3715d3383098c88c1b0.png" />
    </Frame>
  </Tab>

  <Tab title="Anniversary billing period">
    Another option is to use the **anniversary date** of the subscription to define a custom billing period.

    For example:

    > Your customer signs up for the Premium plan on August 10th.
    > If you choose to align the billing cycle with the anniversary date of the subscription, the customer will be billed every 10th of the month.
    > The first billing period will run from August 10th to September 9th.

    <Frame caption="Anniversary billing cadence">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/subscriptions/images/anniversary-date-c66bee86224946e6e00af9c0cb7eedeb.png" />
    </Frame>
  </Tab>
</Tabs>

## Subscription start date

By default, the subscription starts the day it is created. However, you can set a subscription date in the past or in the future.
The subscription date displayed in the app is based on the organization's timezone.
However, you can decide to start a subscription **in the past** or **in the future**.

<Tabs>
  <Tab title="Start date in the past">
    If the start date of the subscription is in the past, the subscription is considered active.

    <Info>
      Lago will not generate any invoices for past periods already completed.
    </Info>

    The invoicing process varies depending on the [plan model](/guide/plans/plan-model) and [billing cycle](#billing-cycles):

    *   If the plan includes a subscription fee to be paid in advance, it will be considered as **already paid for the current period**. The next invoice will include the usage-based charges for the current period and the subscription fee for the next period (see example 1 below); and
    *   If the plan includes a subscription fee to be paid in arrears, it will be **included in the next invoice**, together with the usage-based charges for the current period (see example 2 below).

    **Example 1:** Start date in the past and subscription fee to be paid in advance

    <Frame caption="Illustration for start date in the past and subscription fee in advance">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/subscriptions/images/subscription-past-advance-0bedeeb9f9918608568ea7db6479e4ef.png" />
    </Frame>

    **Example 2:** Start date in the past and subscription fee to be paid in arrears

    <Frame caption="Illustration for start date in the past and subscription fee in advance">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/subscriptions/images/subscription-past-arrears-b4f22483b4ae3a358c0b27305e49a766.png" />
    </Frame>
  </Tab>

  <Tab title="Start date in the future">
    If the start date of the subscription is in the future, the subscription is considered pending.

    The invoicing process varies depending on the [plan model](/guide/plans/plan-model) and [billing cycle](#billing-cycles):

    *   If the plan includes a subscription fee to be paid in advance, when the subscription becomes active, Lago will automatically generate an **invoice for the subscription fee**. Usage-based charges will be included in the next invoice, generated at the end of the billing period (see example 3 below); and
    *   If the plan includes a subscription fee to be paid in arrears, when the subscription becomes active, **there will be no invoice**. The subscription fee and usage-based charges will be included in the invoice generated at the end of the billing period (see example 4 below).

    **Example 3:** Start date in the future and subscription fee to be paid in advance

    <Frame caption="Illustration for start date in the future and subscription fee in advance">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/subscriptions/images/subscription-future-advance-e0c8d632579fe11dfc530987d86ca211.png" />
    </Frame>

    **Example 4:** Start date in the future and subscription fee to be paid in arrears

    <Frame caption="Illustration for start date in the future and subscription fee in arrears">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/subscriptions/images/subscription-future-arrears-8b99c7c98e2f8223d6282fd5f47a665a.png" />
    </Frame>
  </Tab>
</Tabs>

## Subscription end date

By default, if no subscription end date is specified, **the subscription will automatically renew at the end of the period**.

However, if you define an end date, the subscription will terminate on that date without renewal. This is valuable for contracts with specific termination dates.

Keep in mind, 45 days and 15 days before the subscription ends, a webhook alert, called `subscription.termination_alert`, will remind you. You then have two choices:

1.  Allow the subscription to continue until the end date and finalize it; or
2.  Adjust the subscription end date if the contract has been renegotiated.

<Info>
  Ensure that the subscription end date is set to a date later than the subscription start date.
</Info>

<Tabs>
  <Tab title="Dashboard">
    Here is how you can define a susbcription end date from the UI:

    1.  Access the **"Customers"** section via the side menu;
    2.  Select a customer from the list;
    3.  In the **"Overview"** tab, click **"Add a plan"** on the right;
    4.  Set a subscription start date;
    5.  Set a subscription end date;
    6.  Choose between calendar or anniversary billing;
    7.  Click **"Add plan"** to confirm.
  </Tab>

  <Tab title="API">
    Use the `ending_at` field on the subscriptions endpoint.

    <CodeGroup>
      ```bash Define a subscription end date
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/subscriptions" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "subscription": {
          "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "plan_code": "premium",
          "external_id": "my_sub_12345789",
          "name": "Repository 1",
          "subscription_at": "2022-08-08T00:00:00Z",
          "ending_at": "2023-08-08T00:00:00Z",
          "billing_time": "anniversary"
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Multiple plans

You may create several subscriptions for a customer by assigning them multiple plans. This can be particularly useful if your application allows customers to create different projects or workspaces (e.g. Free plan for Workspace 1, Free plan for Workspace 2, Premium plan for Workspace 3, etc.).

<Warning>
  There are some rules to keep in mind when assigning multiple plans to a customer:

  1.  All plans must be denominated in the same currency; and
  2.  You must specify the `external_subscription_id` for each event or create [batch events](/api-reference/events/batch).
</Warning>

We recommend that you give each subscription a name when assigning multiple plans to a customer. The subscription names will make it easier to differentiate each plan and will also be displayed on the invoices.

When multiple subscriptions are linked to a customer, Lago will automatically consolidate invoices when possible.

|                  | Month 1 | Month 2 | Month 3 | Month 4 | (...) | Month 13 |
| ---------------- | ------- | ------- | ------- | ------- | ----- | -------- |
| Plan A (monthly) | \$40    | \$40    | \$40    | \$40    | (...) | \$40     |
| Plan B (monthly) | \$60    | \$60    | \$60    | \$60    | (...) | \$60     |
| Plan C (yearly)  | \$500   | -       | -       | -       | (...) | \$500    |
| Total invoice    | \$600   | \$100   | \$100   | \$100   | (...) | \$600    |

It is possible to link to the same customer subscriptions that are based on different billing cycles (e.g. a subscription based on calendar dates and another based on the anniversary date).

## Overriding a plan

<Info>
  **PREMIUM FEATURE** ✨

  This feature is only available to users with a premium license. Please
  **[contact us](mailto:hello@getlago.com)** to get access to Lago Cloud and Lago
  Self-Hosted Premium.
</Info>

By assigning a subscription to a customer, you gain the flexibility to customize certain aspects of the initially selected plan.
This enables you to maintain a consistent plan structure for all customers while tailoring individualized discounts through price adjustments per customer.

<Tabs>
  <Tab title="Dashboard">
    To perform a plan overrides, assign a plan to a customer and you’ll be able to make modifications to the following elements:

    1.  Subscription invoice display name
    2.  Subscription fee
    3.  Plan currency
    4.  Plan trial period
    5.  Plan taxes
    6.  Charges properties (please note that the charge model cannot be modified)
    7.  Charge group definitions & properties (if applicable)
    8.  Charge minimum spending
    9.  Charge taxes
    10. Charge invoice display name
    11. [Progressive billing](/guide/plans/progressive-billing) thresholds
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Override a plan
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/subscriptions" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
        "subscription": {
          "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "plan_code": "premium",
          "external_id": "my_new_sub_123456789",
          "name": "",
          "subscription_at": "2022-08-08T00:00:00Z",
          "ending_at": "2023-08-08T00:00:00Z",
          "billing_time": "anniversary",
          "plan_overrides": {
            "name": "new_plan",
            "invoice_display_name": "Subscription fee",
            "description": "Overriden plan for customer X",
            "amount_cents": 10000,
            "amount_currency": "USD",
            "trial_period": "0",
            "tax_codes": [
              "vat_10"
            ],
            "charges": [
              {
                "id": "cac4cff7-e2d9-41e2-83e5-7947d91f0eb5",
                "invoice_display_name": "Cards - custom price",
                "billable_metric_code": "cards",
                "min_amount_cents": 0,
                "properties": {
                  "amount": "10"
                },
                "group_properties": [],
                "taxes": []
              }
            ]
          }
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

It's crucial to note that all overridden plans will remain associated with the initial plan but won't be visible in the plans list.
To access an overridden plan, simply click on the specific subscription item in the customer details view.

Moreover, all invoices generated from this subscription will be based from the overridden plan, not the initial plan.
Additionally, any coupons restricted to a plan code will apply to both the initial and overridden plans.

Importantly, any changes made to the initial plans will not impact the subscriptions linked to overridden plans.

## Deleting a plan

You could [delete a plan](/api-reference/plans/destroy) linked to existing subscriptions.

If you do so, the subscriptions associated with this plan will be immediately terminated. This action may trigger the generation of invoices and/or credit notes.

<Info>
  After deleting a plan, you can create a new one using the same code.
</Info>


# Edit a subscription

You can edit a subscription at any time, whether it's active or pending.

Once a plan has been assigned to a customer, whether it's in a pending or active state, you can make edits to the subscription by following these steps:

<Tabs>
  <Tab title="Dashboard">
    1.  Click on the three dots menu icon and select "Edit subscription."
    2.  Subscription Start and End Date\
        You have the ability to modify the subscription start date if the subscription is pending, and if the chosen date is later than today. It's important to refer to the [guidelines for subscription start date](https://docs.getlago.com/guide/subscriptions/assign-plan#subscription-start-date) for further information.
    3.  Subscription End Date\
        You can also make changes to the subscription end date, but it's important to refer to the [guidelines for subscription end date](https://docs.getlago.com/guide/subscriptions/assign-plan#subscription-end-date) for further information.
    4.  You can edit any prices listed for a subscription, including charges, commitments, tiers and spending minimums.
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Override a plan
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request PUT "$LAGO_URL/api/v1/subscriptions/{external_id}" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
        "subscription": {
          "name": "",
          "subscription_at": "2022-08-08T00:00:00Z",
          "ending_at": "2023-08-08T00:00:00Z",
          "plan_overrides": {
            "name": "new_plan",
            "invoice_display_name": "Subscription fee",
            "description": "Overriden plan for customer X",
            "charges": [
              {
                "id": "cac4cff7-e2d9-41e2-83e5-7947d91f0eb5",
                "invoice_display_name": "Cards - custom price",
                "properties": {
                  "amount": "10"
                },
                "group_properties": [],
              }
            ]
          }
        }
      }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>


# Terminate a subscription

You can terminate a subscription at any time, whether it's active or pending.

## Terminate an active subscription

<Tabs>
  <Tab title="Dashboard">
    To terminate an active subscription through the user interface:

    1.  Access the **"Customers"** section via the side menu;
    2.  Select a customer from the list;
    3.  In the **"Overview"** tab, select an active subscription; and
    4.  Click **"Terminate subscription"**; and to terminate an active subscription.
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Terminate an active subscription
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"
        EXTERNAL_ID="__YOUR_SUBSCRIPTION_ID__"

        curl --location --request DELETE "$LAGO_URL/api/v1/subscriptions/$EXTERNAL_ID" \
          --header "Authorization: Bearer $API_KEY"

      ```
    </CodeGroup>
  </Tab>
</Tabs>

When a subscription is terminated:

*   Lago automatically generates an invoice for any outstanding usage-based charges that have not been invoiced yet;
*   If the subscription fee for the plan has been paid in advance, Lago automatically issues a credit note for the unused number of days.

## Terminate a pending subscription

<Tabs>
  <Tab title="Dashboard">
    To terminate a pending subscription through the user interface:

    1.  Access the **"Customers"** section via the side menu;
    2.  Select a customer from the list;
    3.  In the **"Overview"** tab, select a pending subscription (subscription set in the future or pending downgrade); and
    4.  Click **"Terminate subscription"**; and to cancel a pending subscription subscription.
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Terminate a pending subscription
          LAGO_URL="https://api.getlago.com"
          API_KEY="__YOUR_API_KEY__"
          EXTERNAL_ID="__YOUR_SUBSCRIPTION_ID__"

          curl --location --request DELETE "$LAGO_URL/api/v1/subscriptions/$EXTERNAL_ID?status=pending" \
            --header "Authorization: Bearer $API_KEY"
      ```
    </CodeGroup>
  </Tab>
</Tabs>

<Warning>
  To ensure the termination of a pending subscription, it is crucial to include the `?status=pending` filter in your endpoint.
  Neglecting to do so will render any termination attempts ineffective.
</Warning>


# Upgrades and downgrades

Customers have the flexibility to easily upgrade or downgrade their plan at any given moment.

<Tabs>
  <Tab title="Dashboard">
    To perform an upgrade or a downgrade through the user interface:

    1.  Access the **"Customers"** section via the side menu;
    2.  Select a customer from the list;
    3.  In the **"Overview"** tab. By clicking the ellipse icon, you can **"Upgrade/downgrade plan"**;
    4.  Give a name to the new subscription (name that will be displayed on the invoice - optional);
    5.  Provide a new subscription end date if needed (optional);
    6.  Click **"Upgrade/downgrade plan"** to confirm.
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Upgrade or downgrade a subscription
      curl --request POST \
      --url https://api.getlago.com/api/v1/subscriptions \
      --header 'Bearer: <bearer>' \
      --data '{
        "subscription": {
            "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
            "plan_code": "new_plan",
            "external_id": "existing_sub_id"
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Upgrades behavior

An upgrade occurs when the subscription fee of the new plan, calculated on a daily basis, equals or exceeds the subscription fee of the previous plan,
regardless of the pricing for usage-based charges.

When a subscription is upgraded:

*   Lago promptly applies the new plan to the customer; and
*   In the case of a subscription that is paid in advance (at the beginning of the period), Lago issues a credit note for the unused days from the former plan.

## Downgrades behavior

A downgrade occurs when the subscription fee of the new plan, calculated on a daily basis is lower than the subscription fee of the previous plan,
regardless of the pricing for usage-based charges.

When a subscription is downgraded:

*   The new plan is applied at the end of the current billing period to ensure that your customer fully benefits from the plan they have already paid for. The newly applied plan will be in a pending state.


# Overview

Since usage-based charges can be calculated at the end of the billing period, you often need to wait to collect payments. With prepaid credits, you can now unlock recurring revenue opportunities for pay-as-you-go pricing models.

Prepaid credits increase predictability as they allow you to collect payments in advance and then monitor the evolution of the balance of your customer’s wallets.

## Create wallets[](#create-wallets "Direct link to heading")

<Tabs>
  <Tab title="Dashboard">
    To create a wallet for one of your customers through the user interface:

    1.  Access the **"Customers"** section via the side menu;
    2.  Select a customer from the list;
    3.  Open the **"Wallets"** and click **"Add a wallet & credits"** on the right;
    4.  Choose a name for the wallet (optional);
    5.  Set the credit value (e.g. 1 credit = \$5);
    6.  Enter the number of credits to be purchased and/or granted for free;
    7.  Define transaction metadata (optional & available only via API);
    8.  Determine whether the wallet transaction generates an invoice after a top-up or only following a successful payment;
    9.  Set the [expiration date](#expiration-date-and-termination) (optional); and
    10. Click **"Add wallet & credits"** to confirm.

    <Info>
      If the currency of the customer is already defined, the currency of the wallet
      must be the same.
    </Info>
  </Tab>

  <Tab title="API">
    ```bash Create a credit wallet
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request POST "$LAGO_URL/api/v1/wallets" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "wallet": {
          "external_customer_id": "hooli_1234",
          "name": "Prepaid credits",
          "rate_amount": "1.0",
          "paid_credits": "100.0",
          "granted_credits": "50.0",
          "currency": "USD",
          "expiration_at": "2022-07-07",
          "invoice_requires_successful_payment": false,
          "transaction_metadata": [
            {
              "key": "top-up-type",
              "value": "manual"
            }
          ]
        }
      }'
    ```
  </Tab>
</Tabs>

![Creation of a wallet via the user interface](https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/new-wallet.png)

Free credits are added to the customer's wallet instantly, while purchased
credits are added to the wallet when payment is confirmed (see below).

Each customer can only have one active wallet.

## Real time wallet balance[](#real-time-wallet-balance "Direct link to heading")

<Info>
  **PREMIUM FEATURE** ✨

  This feature is only available to users with a premium license. Please
  **[contact us](mailto:hello@getlago.com)** to get access to Lago Cloud and Lago
  Self-Hosted Premium.
</Info>

Keep track of your wallet's real-time balance. Lago provides two types of balances for your wallet:

1.  **Balance:** invoiced balance, which reflects the remaining prepaid credits in your wallet. It updates each time an invoice is finalized for the customer.
2.  **Ongoing Balance:** balance accounted for current usage, including taxes, offering a real-time estimate of your balance's consumption. It refreshes every 5 minutes or upon the finalization of an invoice for the customer.

## Application scope[](#application-scope "Direct link to heading")

Prepaid credits are deducted from the subtotal of the next invoice(s), after
tax.

![Invoice partially paid with prepaid credits](https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/prepaid-credits-invoice-ecd9e8ad653b516efb08c6b48e1e48fe.png)

<Info>Prepaid credits do not apply to one-off invoices.</Info>

## Invoicing after successful payment option

When enabled, this option delays issuing an invoice for a wallet top-up until a successful payment is made. If disabled, the invoice is issued immediately upon the wallet top-up, regardless of the payment status. This setting applies to all transactions for the wallet, but can be overridden for individual transactions or recurring rules.

## Expiration date and termination[](#expiration-date-and-termination "Direct link to heading")

By default, if you don't set an expiration date, prepaid credits are carried
over to the next billing period until the wallet balance is zero.

If you define an expiration date, when the date is reached, all remaining
credits are **automatically voided**.

To modify the expiration date of the prepaid credits through the user interface:

1.  Open the **"Wallets"** tab and click **"Edit wallet"** on the right;
2.  Select **"Edit information"**;
3.  Modify the expiration date; and
4.  Click **"Edit information"** to confirm.

The expiration date displayed in the app is based on the organization's timezone.

You also have the ability to terminate a wallet manually, before its expiration
date:

1.  Open the **"Wallets"** tab and click **"Edit wallet"** on the right;
2.  Select **"Terminate wallet"**; and
3.  Click again to confirm.

<Warning>
  Terminating a wallet will instantly void all remaining credits. This action
  **cannot be undone**.
</Warning>


# Top-up and void credits

Add and void credits, to the customer's wallet.

## Credit purchases and top-ups[](#credit-purchases-and-top-ups "Direct link to heading")

Lago automatically generates an invoice for each purchase. Taxes do not apply to
credit purchases, which are considered as advance payments.

Payment must be made in order for credits to be added to the customer's wallet
(i.e. the status of the invoice must be `succeeded`).

<Tabs>
  <Tab title="Dashboard">
    To top up a wallet through the user interface:

    1.  Open the **"Wallets"** tab and click **"Edit wallet"** on the right;
    2.  Select **"Top up credit"**;
    3.  Enter the number of credits to be purchased and/or granted for free;
    4.  Define transaction metadata (optional & available only via API);
    5.  Determine whether the wallet transaction generates an invoice after a top-up or only following a successful payment; and
    6.  Click **"Top up credit"** to confirm.

    <Info>Coupons **do not apply** to credit purchases and top-ups.</Info>
  </Tab>

  <Tab title="API">
    ```bash Top up a credit wallet
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request POST "$LAGO_URL/api/v1/wallet_transactions" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "wallet_transaction": {
          "wallet_id": "wallet_1234567890",
          "paid_credits": "20.0",
          "granted_credits": "10.0",
          "invoice_requires_successful_payment": false,
          "metadata": [
            {
              "key": "top-up-type",
              "value": "manual"
            }
          ]
        }
      }'
    ```
  </Tab>
</Tabs>

## Invoicing top-up after successful payment option

When enabled, this option delays issuing an invoice for a wallet top-up until a successful payment is made. If disabled, the invoice is issued immediately upon the wallet top-up, regardless of the payment status.
This setting can be applied to individual transactions.

## Void credits[](#void-credits "Direct link to heading")

You can deduct a specific number of credits from the wallet's balance. Note that this action is instantaneous and cannot be undone.

<Tabs>
  <Tab title="Dashboard">
    To top up a wallet through the user interface:

    1.  Open the **"Wallets"** tab and click **"Edit wallet"** on the right;
    2.  Select **"Void credits"**;
    3.  Enter the number of credits to void;
    4.  Define transaction metadata (optional & available only via API); and
    5.  Click **"Void credits"** to confirm.
  </Tab>

  <Tab title="API">
    ```bash Top up a credit wallet
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request POST "$LAGO_URL/api/v1/wallet_transactions" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "wallet_transaction": {
          "wallet_id": "wallet_1234567890",
          "voided_credits": "20.0",
          "metadata": [
            {
              "key": "top-up-type",
              "value" "manual-void"
            }
          ]
        }
      }'
    ```
  </Tab>
</Tabs>

## Setup recurring top-ups

When creating or editing a wallet, you have the option to enable recurring top-ups. Two methods for recurring top-ups are available: `fixed` and `target`. These can be triggered either based on an `interval` or a `threshold`.

### Fixed recurring top-up

A fixed recurring top-up allows you to add a predetermined number of credits to your wallet, either for purchasing or gifting.

### Target recurring top-up

A target recurring top-up allows you to add a variable amount of credits to your wallet to reach a specific target balance. The top-up amount is determined by the ongoing balance at the trigger moment and the desired target balance.

### Interval trigger

For an `interval` trigger, specify the frequency of the automatic top-up: `weekly`, `monthly`, `quarterly` or `yearly`.

Once the interval is defined, the system will automatically perform a top-up:

*   Weekly, on the same day each week (e.g., every Monday).
*   Monthly, on the same date each month (e.g., every 2nd of the month).
*   Quarterly, on the same date every three months (e.g., every 2nd of the quarter).
*   Yearly, on the same date every year (e.g., every 2nd of January).

<Tabs>
  <Tab title="Dashboard">
    To setup a `interval` recurring top-up through the user interface:

    1.  Create or edit a wallet;
    2.  Trigger on the option `Activate recurring top-up`;
    3.  Select `interval` as recurring type;
    4.  Define your interval;
    5.  Define when the rule should start; and
    6.  Define transaction metadata for the top-ups (optional & available only via API);
  </Tab>

  <Tab title="API">
    ```bash Setup an interval recurring top-up
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request POST "$LAGO_URL/api/v1/wallets" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "wallet": {
          "external_customer_id": "hooli_1234",
          "name": "Prepaid credits",
          "rate_amount": "1.0",
          "paid_credits": "0.0",
          "granted_credits": "0.0",
          "currency": "USD",
          "expiration_at": "2022-07-07",
          "recurring_transaction_rules": [
            {
              "method": "fixed"
              "trigger": "interval",
              "interval": "weekly",
              "started_at": null,
              "paid_credits": "100.0",
              "granted_credits": "0.0",
              "invoice_requires_successful_payment": false,
              "transaction_metadata": [
                {
                  "key": "top-up-type",
                  "value": "automatic"
                }
              ]
            }
          ]
        }
      }'
    ```
  </Tab>
</Tabs>

### Threshold trigger

With a `threshold` trigger, set a specific number of `credits` that will trigger an automatic top-up. Lago monitors the `ongoing balance`, and if it falls below the defined credit threshold, an automatic top-up is initiated.

<Tabs>
  <Tab title="Dashboard">
    To setup a `interval` recurring top-up through the user interface:

    1.  Create or edit a wallet;
    2.  Trigger on the option `Activate recurring top-up`;
    3.  Select `threshold` as recurring type;
    4.  Define the credits threshold; and
    5.  Define transaction metadata for the top-ups (optional & available only via API);
  </Tab>

  <Tab title="API">
    ```bash Set a recurring top-up on creation
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request POST "$LAGO_URL/api/v1/wallets" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "wallet": {
          "external_customer_id": "hooli_1234",
          "name": "Prepaid credits",
          "rate_amount": "1.0",
          "paid_credits": "100.0",
          "granted_credits": "50.0",
          "currency": "USD",
          "expiration_at": "2022-07-07",
          "recurring_transaction_rules": [
            {
              "method": "fixed"
              "trigger": "threshold",
              "threshold_credits": "100.0"
              "paid_credits": "100.0",
              "granted_credits": "0.0",
              "invoice_requires_successful_payment": true,
              "transaction_metadata": [
                {
                  "key": "top-up-type",
                  "value": "automatic"
                }
              ]
            }
          ]
        }
      }'
    ```
  </Tab>
</Tabs>


# Webhooks



When using Lago, the app generates [several events](/api-reference/webhooks/messages) that you can listen to in order to trigger workflows. Each time an event is generated, you can view it in the Lago application using the webhook logs. This allows you to take a closer look at the generated events, detect possible errors, and retry them.

## Adding a webhook URL

To add a webhook endpoint via the Lago app, follow these steps:

1.  Go to the **Developers** section via the sidebar;
2.  Open the **Webhooks** tab;
3.  Click **Add a webhook**;
4.  Enter the webhook URL;
5.  Choose the webhook signature between JWT and HMAC; and
6.  Click **Add webhook** to confirm.

<Info>
  Note that you can add up to 5 webhook endpoints.
</Info>

## The webhook signature

By creating a webhook endpoint, you have two signature options.

<Tabs>
  <Tab title="Dashboard">
    *   The first is `JWT`, with a possibly lengthy payload header and potential size limits;
    *   The second is `HMAC`, which features a shorter payload header and no size restrictions.

    <Frame caption="Webhook endpoint signature">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/webhook-signature.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    <CodeGroup>
      ```bash Choosing the webhook signature
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/webhook_endpoints" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "webhook_endpoint": {
            "webhook_url": "https://foo.bar",
            "signature_algo": "hmac"
          }
        }'
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Locate your HMAC signature token

To find your HMAC signature token, navigate to **Developers > Webhooks** and locate the **HMAC Signature Token**. Then, reveal and copy the key.

<Frame caption="Locate your HMAC siganture token">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/hmac-signature-token.png" />
</Frame>

## Accessing the webhook logs

Once a webhook is registered in the app, you can access the webhook logs:

1.  Go to the **Developers** section via the sidebar;
2.  Open the **Webhooks** tab;
3.  Click on the webhook endpoint to see the list of events; and
4.  Click the reload icon to see new events (optional).

<Frame caption="Webhook logs">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/images/webhook-logs.png" />
</Frame>

## Accessing a specific event

You can see the details of a specific event by clicking on it. Depending on the event status, you will have access to two or three main blocks:

1.  **A list of properties, including:**
    1.  **Timestamp:** the timestamp of the event;
    2.  **Webhook URL:** the URL used to listen to events;
    3.  **Unique key:** idempotency key associated with the event;
    4.  **Webhook type:** the webhook type used to understand the action triggered;
    5.  **Response:** the response code (i.e. acknowledgement of receipt);
    6.  **Number of retries:** if the event failed, the number of retries attempted;
2.  **A JSON snippet with the arguments sent by Lago; and**
3.  **If the event failed, an error response will be included.**

## Errors and retries

Your webhook server should response with a 2xx (`200`, `201`, `202`, `204`) status code to acknowledge the receipt of the event. If the response is not supported as a success, Lago will consider it as failed.
Some events generated by Lago may not be received on the user side, which is why Lago displays an error status in the user interface.


# NetSuite

Lago seamlessly integrates with NetSuite, enabling real-time synchronization of billing data with your preferred accounting tool.

<Info>
  **PREMIUM ADD-ON** ✨

  This integration is available upon request only. Please **[contact us](mailto:hello@getlago.com)** to get access to this premium integration.
</Info>

## RESTlet script configuration

Lago's native integration with NetSuite utilizes a [custom RESTlet script](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4618456517.html) to provide maximum flexibility in fetching or pushing billing data. To set up the Lago RESTlet script in your NetSuite instance, follow these steps:

### Upload Lago Scripts

1.  In NetSuite, go to **Documents > Files > File Cabinet**;
2.  Under `SuiteScripts`, create a new folder named `Lago`;
3.  **Upload `ramda.min.js`**: This library is essential for using Lago and can be downloaded from [here](https://github.com/ramda/ramda/blob/master/dist/ramda.min.js); and
4.  Upload another file into the `Lago` folder and **paste the script provided by your Lago Account Manager**.

<Frame caption="Upload scripts provided by Lago">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/upload-netsuite-scripts.png" />
</Frame>

### Deploy Lago Scripts

1.  Navigate to **Customization > Scripting > Scripts > Create a New Script**;
2.  Deploy the Lago script for **All roles** and **All employees** (you can create custom roles if needed); and
3.  Make sure to change the script status to `released`.

By deploying this script, you'll generate a **custom endpoint url** that is crucial for the authentication process and enables seamless data synchronization between Lago and NetSuite.

## Mandatory NetSuite settings

To ensure the sync doesn't fail, verify that the following settings are correctly configured. This will enable Lago to sync data to NetSuite properly.

### Remove Locations on invoices and credit memos

Lago doesn't recognize the location field on invoices, which is mandatory by default. To resolve this, remove the location requirement from your invoice form:

1.  Navigate to **Customization > Forms > Transaction Forms**;
2.  Locate the form related to your invoices;
3.  Go to the **Screen Fields** tab; and
4.  Find the Location field and **uncheck both the Show and Mandatory checkboxes**.

<Frame caption="Remove Locations on invoices">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/netsuite-remove-locations-field.png" />
</Frame>

<Info>
  You can repeat the same operation for Credit Memos
</Info>

### Create Lago Tax Nexus, Type and Code

To have Lago override the tax details for your invoice line items, follow these steps. If not, Lago will send the amount excluding taxes to NetSuite.

<Steps>
  <Step title="Step 1: Create a Lago Tax Nexus">
    1.  Go to **Setup** > **Tax** > **Nexuses** > **New**;
    2.  Choose a brand new **Nexus** (⚠️ ensure it's unused by other existing tax nexuses. It can be a new state for an existing country, or a new country.);
    3.  Enter `Lago Tax Nexus` in the **Description** field;
    4.  Create a new **Tax Agency** by clicking the **+** button. Name it `Lago Tax Agency` and assign it to the relevant parent subsidiary;
    5.  Save your new Nexus;
    6.  Add this newly created Nexus to the targeted NetSuite Subsidiaries by navigating to **Setup > Company > Subsidiaries**. Select the parent subsidiary, and add this new nexus in the **Tax Registrations** tab; and
    7.  Ensure that the tax engine for this registration is set to `SuiteTax Engine`.
  </Step>

  <Step title="Step 2: Create a Lago Tax Type">
    1.  Navigate to **Setup** > **Tax** > **Tax Types** > **New**;
    2.  Select the same **Country** as the one used in the Lago Tax Nexus;
    3.  Name it `Lago Tax Type`;
    4.  **Link the Lago Tax Nexus** in the Nexus section;
    5.  Add a **Payables Account** and a **Receivables Account** to this new Tax Type; and
    6.  Save it.
  </Step>

  <Step title="Step 3: Create a Lago Tax Code">
    1.  Go to **Setup** > **Tax** > **Tax Code** > **New**;
    2.  Enter a **Name**, like `Lago Tax`;
    3.  Select and tie the previously created Lago Tax Type; and
    4.  Save your settings.
  </Step>
</Steps>

### Define Taxable items

To enable tax amount overrides for your Lago invoices synced to NetSuite, ensure all items are marked as taxable. If any item is non-taxable, the invoice sync will fail. To update an item:

1.  Go to **Lists > Accounting > Items**;
2.  Edit the item associated with a Lago object;
3.  Navigate to the **Accounting** tab;
4.  Locate the **Tax / Tariff** section; and
5.  Set the item to **Taxable**.

<Frame caption="Define Taxable items">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/netsuite-taxable-items.png" />
</Frame>

## Connecting Lago to NetSuite

To fully integrate Lago with NetSuite, start by connecting your Lago instance to a new NetSuite connection.
You can have an unlimited number of NetSuite connections. First, link your NetSuite account to Lago.
Once connected, activate the specific syncs and actions required for your use case.
This ensures that your Lago instance is properly configured to communicate with NetSuite, enabling seamless data synchronization and management.

### Create a new integration in NetSuite

After logging into your NetSuite account, navigate to **Setup > Integration > Manage Integrations > New**.
Enter the required integration details and follow these steps:

*   Make sure the [oAuth feature is enabled](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_157771482304.html#To-enable-OAuth-2.0-feature%3A) for your NetSuite instance;
*   Make sure the *SOAP WEB SERVICES* and *REST WEB SERVICES* features are enabled in **NetSuite > Company > Enable Features > SuiteCloud**;
*   Under Authentication, select **TOKEN-BASED AUTHENTICATION**;
*   Disable *TBA: AUTHORIZATION FLOW* and *AUTHORIZATION CODE GRANT*; and
*   Save your new integration.

The Client Credentials will be displayed. **Copy the `Consumer Key/Client ID` and `Consumer Secret/Client Secret`** and save them in a secure document for future reference, as this information will not be accessible once you leave the screen.

<Frame caption="Create a new NetSuite Integration">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/netstuite-tba-integration.png" />
</Frame>

### Create a new access token in NetSuite

*   Log into your NetSuite account and navigate to the homepage by **clicking the home icon**;
*   In the **Settings** section at the bottom left corner, locate and click the **Manage Access Tokens** button;
*   Select the **Application Name** created for this integration;
*   Enter a **token Name**; and
*   Save your new access token.

The Token Credentials will be displayed. **Copy the `Token ID` and `Token Secret`** and save them in a secure document for future reference, as this information will not be accessible once you leave the screen.

<Frame caption="Create a new NetSuite My Access Token">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/create-netsuite-token.png" />
</Frame>

### Authentication flow

The authentication process connects Lago and NetSuite through OAuth2.
To establish this connection, you need to provide the following mandatory fields:

*   **Connection Name:** an internal name for the connection within Lago;
*   **Unique Connection Code:** an internal code for the connection within Lago;
*   **NetSuite Account ID:** your NetSuite [account identifier](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_1498754928.html#:~:text=You%20can%20find%20your%20NetSuite,an%20underscore%2C%20for%20example%20123456_RP.);
*   **NetSuite Client ID:** the [client ID](/integrations/accounting/netsuite#create-a-new-integration-in-netsuite) from your NetSuite account;
*   **NetSuite Client Secret:** the [client secret](/integrations/accounting/netsuite#create-a-new-integration-in-netsuite) from your NetSuite account;
*   **NetSuite Token Id:** the [token ID](/integrations/accounting/netsuite#create-a-new-access-token-in-netsuite) from your NetSuite account;
*   **NetSuite Token Secret:** the [token secret](/integrations/accounting/netsuite#create-a-new-access-token-in-netsuite) from your NetSuite account;
*   **Custom RESTlet Endpoint:** The endpoint created from the [custom RESTlet script](/integrations/accounting/netsuite#restlet-script-configuration).

### Enable actions and syncs

Here is a list of syncs and actions that Lago uses with NetSuite. Some are mandatory, while others are optional:

*   `Accounts`: Fetch account data from NetSuite *(mandatory)*;
*   `Customers`: Syncs or fetch customer data from NetSuite *(mandatory)*;
*   `Items` and `Tax Items`: Fetch item and tax item data from NetSuite *(mandatory)*;
*   `Invoices`: Syncs invoice data to NetSuite *(mandatory)*;
*   `Sales Orders`: Syncs sales order data to NetSuite *(optional)*;
*   `Credit Notes`: Syncs credit note data to NetSuite *(optional)*; and
*   `Payments`: Syncs payment data to NetSuite *(optional)*.

<Frame caption="Connect Lago to NetSuite">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/connect-netsuite-to-lago.png" />
</Frame>

## Mapping items between Lago and NetSuite

To sync invoices, credit notes, sales orders, and payments to NetSuite, Lago establishes a one-to-one relationship between Lago objects and NetSuite objects.
Follow these steps to map an item:

*   **Access a NetSuite Connection in Lago:** navigate to your connected NetSuite integration within the Lago platform;
*   **Select the Item to map:** click on the specific item in Lago that you wish to map to a corresponding NetSuite item;
*   **Fetch Items from NetSuite:** Lago will automatically retrieve the relevant items from your NetSuite instance;
*   **Map the Item:** choose the appropriate NetSuite item from the list provided by Lago; and
*   **Click 'Save'** to finalize the mapping.

### Mapping a fallback item (mandatory)

The fallback item is a dummy item used as a backup in case the mapping of other objects fails.
To ensure continuous data synchronization between Lago and NetSuite, this fallback item will be used whenever there is a mapping issue.

<Info>
  This mapping follows a one-to-many structure, meaning that a single fallback item can be used to handle multiple mapping issues.
</Info>

<Frame caption="Map a fallback item between Lago and NetSuite">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/netsuite-fallback-item.png" />
</Frame>

### Mapping a tax item

To override the tax amount for an invoice, sales order, or credit note, you need to map a single tax item from NetSuite.
This mapped item will be used to assign the correct tax amount.

**To ensure taxes are sent from Lago to NetSuite, complete the tax mapping** for the following [tax fields you created here](#create-lago-tax-nexus-type-and-code):

1.  Tax Nexus;
2.  Tax Type; and
3.  Tax Code.

Use the `id` for each item, found either in the UI or in the URL of the specific item.

<Info>
  This mapping follows a one-to-many structure, meaning that a single tax item can be mapped to override all tax amounts issued by Lago.
</Info>

<Frame caption="Map a tax item between Lago and NetSuite">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/mapping-tax-item-netsuite.png" />
</Frame>

### Mapping default objects

Coupons, credit notes, subscription fees, minimum commitments, and prepaid credits require a one-to-many mapping.
Each of these objects must be mapped to a single default item from your NetSuite instance. Lago will use this mapped item
whenever any of these objects appear on the final invoice sent to NetSuite.

<Info>
  This mapping follows a one-to-many structure, meaning a single item can handle multiple mappings for coupons, credit notes, subscription fees, minimum commitments, and prepaid credits.
</Info>

<Frame caption="Map default items between Lago and NetSuite">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/mapping-default-items-netsuite.png" />
</Frame>

### Mapping custom objects

Billable metrics and add-ons require a one-to-one mapping. Each billable metric, used for usage-based billing, must represent a specific SKU in your NetSuite instance.
You need to map each of these individually. Lago will use the mapped items whenever any of these metrics or add-ons appear on the final invoice sent to NetSuite.

<Info>
  This mapping follows a one-to-one structure, meaning each billable metric or add-on must be mapped to a specific NetSuite item.
</Info>

<Frame caption="Map custom items between Lago and NetSuite">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/mapping-custom-items-netsuite.png" />
</Frame>

## Customers synchronization

When creating or updating a Lago customer, you can choose to link it to a NetSuite customer.

The first option is to **automatically create a new customer from Lago to NetSuite**. Follow these steps:

1.  Create or update a new Lago customer;
2.  Select the targeted NetSuite connection;
3.  Check the box labeled 'Create this customer automatically in NetSuite';
4.  Choose a NetSuite subsidiary from the list (Lago will fetch the list of subsidiaries from your NetSuite instance); and
5.  Save and create this new customer.

If the customer is successfully created in NetSuite, a new field will be displayed in the Lago customer view, providing a direct link to the corresponding NetSuite customer.

<Info>
  Customer creation from Lago to NetSuite happens in real-time with only a few seconds of delay.
</Info>

<Frame caption="Lago customer integrated with NetSuite">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/sync-customers-netsuite.png" />
</Frame>

The second option is to **import an existing NetSuite customer to a Lago customer**. Follow these steps:

1.  Create or update a Lago customer;
2.  Select the targeted NetSuite connection;
3.  Ensure the box labeled 'Create this customer automatically in NetSuite' is unchecked;
4.  Paste the NetSuite customer ID in the appropriate field; and
5.  Save and create this new customer.

**Here is the list of fields that is currently synced to NetSuite:**

| Lago                              | NetSuite                 |
| --------------------------------- | ------------------------ |
| customer                          | type                     |
| customer.name                     | companyname              |
| customer.netsuite\_subsidiary     | subsidiary               |
| customer.id                       | custbody\_lago\_id       |
| customer.email                    | email                    |
| customer.phone                    | phone                    |
| customer.external\_salesforce\_id | custentity\_lago\_sf\_id |

## Invoices synchronization

If a Lago customer is linked to a NetSuite customer, Lago syncs invoices to NetSuite Invoices in real-time.

It's important to note the following:

*   Each fee issued by Lago is synced as a line item on a NetSuite invoice;
*   The Lago fee `units` are synced to NetSuite as `quantity`;
*   The Lago fee `precise_unit_amount` is synced to NetSuite as `rate`;
*   Lago overrides the total tax amount of a NetSuite invoice using the tax item, as NetSuite does not support tax details at the line item level; and
*   Any discounts on an invoice (coupon, credit note, or prepaid credits) are synced as negative line items on the NetSuite invoice.

If the invoice is successfully created in NetSuite, a new field will be displayed in the Lago invoice view, providing a direct link to the corresponding NetSuite invoice.

<Info>
  Invoice creation from Lago to NetSuite happens in real-time with only a few seconds of delay.
</Info>

<Frame caption="Sync Lago invoices to NetSuite">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/sync-invoices-netsuite.png" />
</Frame>

**Here is the list of fields that is currently synced to NetSuite:**

| Lago                              | NetSuite           |
| --------------------------------- | ------------------ |
| invoice                           | type               |
| invoice.lago\_id                  | tranid             |
| customer.netsuite\_internal\_id   | entity             |
| true                              | istaxable          |
| taxitem.id                        | taxitem            |
| invoice.taxes\_amount\_cents      | taxamountoverride  |
| invoice.number                    | otherrefnum        |
| invoice.lago\_id                  | custbody\_lago\_id |
| invoice.fee.id                    | lineItems.item     |
| invoice.fee.account\_code         | lineItems.account  |
| invoice.fee.units                 | lineItems.quantity |
| invoice.fee.precise\_unit\_amount | lineItems.rate     |

## Sales Orders synchronization

If a Lago customer is linked to a NetSuite customer and the Sales Orders action is enabled in your Lago-NetSuite connection, Lago syncs invoices to NetSuite Sales Orders in real-time.

Note that the same fields used to sync invoices are also used to sync sales orders.

**Here is the list of fields that is currently synced to NetSuite:**

| Lago                              | NetSuite           |
| --------------------------------- | ------------------ |
| salesorder                        | type               |
| invoice.lago\_id                  | tranid             |
| customer.netsuite\_internal\_id   | entity             |
| true                              | istaxable          |
| taxitem.id                        | taxitem            |
| invoice.taxes\_amount\_cents      | taxamountoverride  |
| invoice.number                    | otherrefnum        |
| invoice.lago\_id                  | custbody\_lago\_id |
| invoice.fee.id                    | lineItems.item     |
| invoice.fee.account\_code         | lineItems.account  |
| invoice.fee.units                 | lineItems.quantity |
| invoice.fee.precise\_unit\_amount | lineItems.rate     |

## Credit Notes synchronization

If a Lago customer is linked to a NetSuite customer, Lago syncs credit notes to NetSuite Credit Memos in real-time.

It's important to note the following:

*   Each fee refunded by Lago is synced as a line item on a NetSuite Credit Memo;
*   Lago overrides the total tax amount of a NetSuite credit memo using the tax item, as NetSuite does not support tax details at the line item level; and
*   Any discounts on an credit note (like coupon, for instance) are synced as line items on the NetSuite Credit Memo.

If the credit note is successfully created in NetSuite, a new field will be displayed in the Lago credit note view, providing a direct link to the corresponding NetSuite Credit Memo.

<Info>
  Credit note creation from Lago to NetSuite happens in real-time with only a few seconds of delay.
</Info>

**Here is the list of fields that is currently synced to NetSuite:**

| Lago                              | NetSuite           |
| --------------------------------- | ------------------ |
| creditmemo                        | type               |
| invoice.lago\_id                  | tranid             |
| customer.netsuite\_internal\_id   | entity             |
| true                              | istaxable          |
| taxitem.id                        | taxitem            |
| invoice.taxes\_amount\_cents      | taxamountoverride  |
| invoice.number                    | otherrefnum        |
| invoice.lago\_id                  | custbody\_lago\_id |
| invoice.fee.id                    | lineItems.item     |
| invoice.fee.account\_code         | lineItems.account  |
| invoice.fee.units                 | lineItems.quantity |
| invoice.fee.precise\_unit\_amount | lineItems.rate     |

## Payments synchronization

If a Lago invoice is tied to a NetSuite invoice, Lago automatically syncs payments occurring in Lago to NetSuite, updating in-real time the payment status of the invoice in NetSuite.

| Lago                            | NetSuite         |
| ------------------------------- | ---------------- |
| customerpayment                 | type             |
| customer.netsuite\_internal\_id | customer         |
| invoice.netsuite\_internal\_id  | lineItems.doc    |
| true                            | lineItems.apply  |
| invoice.total\_amount\_cents    | lineItems.amount |

## Integration logs

Whenever an issue occurs in NetSuite, Lago will notify you through a [webhook message](/api-reference/webhooks/messages#accounting-provider-error) called `customer.accounting_provider_error`.


# Xero

Lago seamlessly integrates with Xero, enabling real-time synchronization of billing data with your preferred accounting tool.

<Info>
  **PREMIUM ADD-ON** ✨

  This integration is available upon request only. Please **[contact us](mailto:hello@getlago.com)** to get access to this premium integration.
</Info>

## Connecting Lago to Xero

To fully integrate Lago with Xero, start by connecting your Lago instance to a new Xero connection.
You can have an unlimited number of Xero connections. First, link your Xero account to Lago.
Once connected, activate the specific syncs and actions required for your use case.
This ensures that your Lago instance is properly configured to communicate with Xero, enabling seamless data synchronization and management.

1.  In Lago, navigate to **Integrations > Xero**;
2.  Create a **new Xero connection**;
3.  Assign a unique **name** and **code** to the connection; and
4.  Use OAuth2 to **grant access** to your Xero instance.

There you go, Lago is fully connected to Xero!

<Frame caption="Granting access to Xero">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/xero-grant-access-lago.png" />
</Frame>

## Enable actions and syncs

Here is a list of syncs and actions that Lago uses with Xero. Some are mandatory, while others are optional:

*   `Accounts`: Fetch account data from Xero *(mandatory)*;
*   `Customers`: Syncs or fetch customer data from Xero *(mandatory)*;
*   `Items`: Fetch item data from Xero *(mandatory)*;
*   `Invoices`: Syncs invoice data to Xero *(mandatory)*;
*   `Credit Notes`: Syncs credit note data to Xero *(optional)*; and
*   `Payments`: Syncs payment data to Xero *(optional)*.

<Frame caption="Granting access to Xero">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/xero-syncs-and-actions.png" />
</Frame>

## Mapping items between Lago and Xero

To sync invoices, credit notes and payments to Xero, Lago establishes a one-to-one relationship between Lago objects and Xero objects. Follow these steps to map an item:

*   **Access a Xero Connection in Lago:** navigate to your connected Xero integration within the Lago platform;
*   **Select the Item to map:** click on the specific item in Lago that you wish to map to a corresponding Xero item;
*   **Fetch Items from Xero:** Lago will automatically retrieve the relevant items from your Xero instance;
*   **Map the Item:** choose the appropriate Xero item from the list provided by Lago; and
*   **Click 'Save'** to finalize the mapping.

### Mapping a fallback item (mandatory)

The fallback item is a dummy item used as a backup in case the mapping of other objects fails.
To ensure continuous data synchronization between Lago and Xero, this fallback item will be used whenever there is a mapping issue.

<Info>
  This mapping follows a one-to-many structure, meaning that a single fallback item can be used to handle multiple mapping issues.
</Info>

<Frame caption="Map a fallback item between Lago and Xero">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/xero-mapping-fallback-item.png" />
</Frame>

### Mapping a payment account (mandatory)

To synchronize invoice payments between Lago and Xero, ensure that at least one payment account is mapped.

To set up a payment account in Xero, follow these steps:

1.  Log in to your Xero instance;
2.  Navigate to **Accounting > Chart of Accounts**;
3.  Select an existing revenue account or create a new one; and
4.  When editing or creating the account, ensure the **'Enable payments to this account'** checkbox is selected.

In Lago, you can now map it in the dedicated section '**Account linked to payments**'.

<Frame caption="Map a fallback item between Lago and Xero">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/xero-create-payment-account.png" />
</Frame>

### Mapping custom objects

Billable metrics and add-ons require a one-to-one mapping. Each billable metric, used for usage-based billing, must represent a specific SKU in your Xero instance.
You need to map each of these individually. Lago will use the mapped items whenever any of these metrics or add-ons appear on the final invoice sent to Xero.

<Info>
  This mapping follows a one-to-one structure, meaning each billable metric or add-on must be mapped to a specific Xero item.
</Info>

<Frame caption="Map custom items between Lago and Xero">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/xero-mapping-custom-objects.png" />
</Frame>

## Customers synchronization

When creating or updating a Lago customer, you can choose to link it to a Xero customer.

The first option is to **automatically create a new customer from Lago to Xero**. Follow these steps:

1.  Create or update a new Lago customer;
2.  Select the targeted Xero connection;
3.  Check the box labeled 'Create this customer automatically in Xero'; and
4.  Save and create this new customer.

If the customer is successfully created in Xero, a new field will be displayed in the Lago customer view, providing a direct link to the corresponding Xero customer.

<Info>
  Customer creation from Lago to Xero happens in real-time with only a few seconds of delay.
</Info>

<Frame caption="Lago customer integrated with Xero">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/xero-sync-customers.png" />
</Frame>

The second option is to **import an existing Xero customer to a Lago customer**. Follow these steps:

1.  Create or update a Lago customer;
2.  Select the targeted Xero connection;
3.  Ensure the box labeled 'Create this customer automatically in Xero' is unchecked;
4.  Paste the Xero customer ID in the appropriate field; and
5.  Save and create this new customer.

**Here is the list of fields that is currently synced to Xero:**

| Lago                                 | Xero         |
| ------------------------------------ | ------------ |
| customer                             | type         |
| customer.name                        | Name         |
| customer.email                       | EmailAddress |
| customer.phone                       | Phones       |
| customer.tax\_identification\_number | TaxNumber    |
| customer.address\_line\_1            | AddressLine1 |
| customer.address\_line\_2            | AddressLine2 |
| customer.city                        | City         |
| customer.zip                         | PostalCode   |
| customer.country                     | Country      |
| customer.state                       | Region       |

## Invoices synchronization

If a Lago customer is linked to a Xero customer, Lago syncs invoices to Xero Invoices in real-time.

It's important to note the following:

*   Each fee issued by Lago is synced as a line item on a Xero invoice;
*   The Lago fee `units` are synced to Xero as `Quantity`;
*   The Lago fee `precise_unit_amount` is synced to Xero as `UnitAmount`;
*   Lago can send the total tax amount for a specific line item; and
*   Lago can apply discount to a specific line item.

If the invoice is successfully created in Xero, a new field will be displayed in the Lago invoice view, providing a direct link to the corresponding Xero invoice.

<Info>
  Invoice creation from Lago to Xero happens in real-time with only a few seconds of delay.
</Info>

<Frame caption="Sync Lago invoices to Xero">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/xero-sync-invoices.png" />
</Frame>

**Here is the list of fields that is currently synced to Xero:**

| Lago                                        | Xero           |
| ------------------------------------------- | -------------- |
| invoice                                     | type           |
| invoice.number                              | InvoiceNumber  |
| invoice.status                              | Status         |
| invoice.currency                            | CurrencyCode   |
| invoice.issuing\_date                       | Date           |
| invoice.payment\_due\_date                  | DueDate        |
| invoice.fee.units                           | Quantity       |
| invoice.fee.precise\_unit\_amount           | UnitAmount     |
| invoice.fee.amount\_cents                   | LineAmount     |
| invoice.fee.taxes\_amount\_cents            | TaxAmount      |
| invoice.fee.precise\_coupons\_amount\_cents | DiscountAmount |

## Credit Notes synchronization

If a Lago customer is linked to a Xero customer, Lago syncs credit notes to Xero Credit Notes in real-time.

It's important to note the following:

*   Each fee refunded by Lago is synced as a line item on a Xero Credit Note; and
*   Any discounts on an credit note (like coupon, for instance) are synced as line items on the Xero Credit Note.

If the credit note is successfully created in Xero, a new field will be displayed in the Lago credit note view, providing a direct link to the corresponding Xero Credit Note.

<Info>
  Credit note creation from Lago to Xero happens in real-time with only a few seconds of delay.
</Info>

**Here is the list of fields that is currently synced to Xero:**

| Lago                                          | Xero             |
| --------------------------------------------- | ---------------- |
| credit\_note.number                           | CreditNoteNumber |
| credit\_note.reference                        | Reference        |
| credit\_note.status                           | Status           |
| credit\_note.currency                         | CurrencyCode     |
| credit\_note.issuing\_date                    | Date             |
| credit\_note.line\_item.units                 | Quantity         |
| credit\_note.line\_item.precise\_unit\_amount | UnitAmount       |
| credit\_note.line\_item.amount\_cents         | LineAmount       |
| credit\_note.line\_item.taxes\_amount\_cents  | TaxAmount        |

## Payments synchronization

If a Lago invoice is tied to a Xero invoice, Lago automatically syncs payments occurring in Lago to Xero, updating in-real time the payment status of the invoice in Xero.

| Lago                  | Xero    |
| --------------------- | ------- |
| invoice.id            | Invoice |
| invoice.amount\_cents | Amount  |

## Integration logs

Whenever an issue occurs in Xero, Lago will notify you through a [webhook message](/api-reference/webhooks/messages#accounting-provider-error) called `customer.accounting_provider_error`.


# N8N



Here is a typical use case of using Lago and N8N to create powerful alerting automation.

## Overconsumption Alerting Example (with N8N)

When one of your customers is overconsuming during a period, you might need to warn her. This might happen for Cloud or API products. Automatic billing does not mean that your customers should have a bad surprise when opening their invoices.

Here is a full workflow to create an alerting system based on your customers' current usage, using [N8N](https://n8n.io/), a powerful automation tool for developers.

<Frame caption="N8N Alerting Workflow">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/alerting/images/n8n-current-usage-ffe518dc30433d5f993f3cfb67a31374.png" />
</Frame>

In this example, we are going to build an alert anytime a usage threshold is overcome. Here is a summary of this workflow:

1.  Use a **Cron** expression to call the Lago API every X minutes/hours/days
2.  Call the [**Current usage**](/api-reference/customer-usage/get-current) endpoint available in Lago to fetch your customers' current usage;
3.  Create a **IF statement** to condition the trigger (in our case, messages are triggered above a specific overconsumption); and
4.  **Send a message** whenever this threshold is reached. You could use an emailing tool, Slack or a CRM. In our case, we are using Slack.

## 1st Node - CRON expression to repeat tasks at a defined interval

The first node is repeatedly and automatically triggering the automation at a defined interval.

1.  Add a new **Node**;
2.  Select **CRON** as a new application node;
3.  The **Mode** is set to `Every X`; and
4.  The **Value** is defined to `10` and the the **Units** to `minutes`.

This will trigger the flow automatically every 10 minutes. You can obviously change the value and the units to your preferred interval.

<Frame caption="Cron expression">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/alerting/images/cron-alerting-a3cc55668cedb59003c788201dcfaf16.png" />
</Frame>

## 2nd Node - Catch customers' current usage with a HTTP Request

This node is used to fetch current usage from Lago API, using a HTTP request.

1.  Add a new **Node**;
2.  Select **HTTP Request** as a new application node;
3.  Fetch [customers' current usage](/api-reference/customer-usage/get-current) from Lago API;
4.  Make sure to set the `API_KEY` and the `Content-Type` as headers of your request; and
5.  Execute the node to fetch the payload from Lago's API.

<Frame caption="Customer current usage">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/alerting/images/current-usage-http-request-f534e90c3cc02f462a65c859218ac063.png" />
</Frame>

## 3rd Node - IF conditional statement to trigger messages under conditions

This node is used to trigger the alert only when your customers overcome a threshold of usage. Those limits depend on your product and your paying features.

In our present use case, we want to trigger an alert **when the total consumption of usage-based features overcomes \$200**. You could also use the `number of units` consumed or another useful value from the payload.

1.  Add a new **Node**;
2.  Select **IF** as a new application node;
3.  Create a condition for the **TRUE** branch (when conditions are met);
4.  The **Value** is the parameter of your condition (in our case the `amount_cents` of the current usage);
5.  The **Operation** is the math operation you want to apply (in our case, condition is met when the total `amount_cents` is larger or equal to \$200);

It is important to mention that:

*   You can add as many conditions as you need;
*   You could add an action when the condition is `FALSE`.

<Frame caption="Customer current usage with if statement">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/alerting/images/if-statement-current-usage-4186fee96e606f9554fa1bbcd6f07f5b.png" />
</Frame>

## 4th Node - Send an alert message to Slack

This last node is used to trigger the message. In the example, we use a Slack channel, but you could even decide to send an email directly to your customers when they pass the limits of usage.

1.  Add a new **Node**;
2.  Select **Slack** as a new application node;
3.  Select the targeted **Slack Account** & **Slack Channel**;
4.  Choose the option to **POST** a **Message**; and
5.  **Define a message** and use the variables of your payload to give context to your customers about their current usage.

<Tip>
  On top of connecting your Slack account, don't forget to authorize the application's bot to post messages to the targeted channel.
</Tip>

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/alerting/images/slack-alert-current-usage-247e699c94c1e5ec0f8adaac4b7abe8e.png" />
</Frame>

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/alerting/images/slack-alert-current-usage-message-dcd840bb5aa02098873410a83eb40776.png" />
</Frame>


# Zapier



Here is a typical use case of using Lago with Zapier to create powerful alerting automation.

## Invoice Alerting Example (with Zapier)

<Frame caption="invoice alerting flow">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/alerting/images/invoice-alerting-flow-6c86d0faab38b7740a20925797099c70.png" />
</Frame>

In this example, we are going to **build an alert anytime a new invoice is emitted**. To create this workflow, we are using:

1.  Lago's webhook when a new invoice is emitted;
2.  Zapier as an automation tool, to catch, tranform and send the data; and
3.  Slack as the "receiver" to alert your team anytime a new invoice is created.

<Frame caption="Zapier alerting flow">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/alerting/images/zapier-flow-invoice-alerting-6916f7acabd57ddc10125d0fe1b9f7e1.png" />
</Frame>

## 1. Catch a webhook when a new invoice is emitted

Lago automatically creates an invoice when a billable period is over. The invoice's payload gives you a detailed view of what has been invoiced. The first action we need to perform is to catch this invoice with a webhook:

1.  In Zapier, create a new Zap;
2.  Use the **Webhooks by Zapier** as the trigger of this Zap;
3.  Select the **Catch Raw Hook** event trigger;
4.  Copy the Zapier Webhook URL and paste it in Lago (**Developers** > **Webhooks** > **Add a webhook**); and
5.  Catch your first webhook when an invoice is emitted (whenever you assign an add-on or a subscription).

## 2. Run a script to transform the webhook

In Zapier, create a second action by clicking the `+` icon. This new event action is used to format the webhook with a breakdown of fields that can be used in a message.

1.  Select **Code by Zapier** as a new *Event Action*;
2.  Click on **Javascript** as the event code language to run;
3.  Create a field called `payload`. The value of this field is the full **Raw body** of your invoice object received);
4.  Run the script (code snippet below) in the **Code** section;
5.  Test the action. If valid, it returns a breakdown of fields.

```javascript
var obj = JSON.parse(inputData.payload);

if(obj.object_type == "invoice"){
  return obj
}
```

<Frame caption="Script to tranform the invoice payload">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/alerting/images/script-invoice-alerting-ad7c8393f51e76b0601c2e153b1ee1dc.png" />
</Frame>

<Frame caption="Breakdown of the invoice payload">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/alerting/images/alerting-fields-breakdown-33a58492027cdcbfe5562d1c1cd96397.png" />
</Frame>

## 3. Send a message to a Slack Channel

Once you catch the breakdown of fields returned by the invoice payload, you can easily use them to create a Slack text message.

In Zapier, create a third action by clicking the `+` icon. This new event action is used to send a message to Slack by using the fields of the invoice payload.

1.  Select **Slack** as a new app action;
2.  Select the **Send Channel Message** action;
3.  Choose the targeted **Slack Account**;
4.  Choose the targeted **Slack Channel**; and
5.  Create a message by using the fields returned by the payload.

By testing and validating the entire Zap, a Slack message is sent anytime a new invoice is emitted by Lago. You can use the same message example as detailed below:

<Frame caption="Breakdown of the invoice payload">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/alerting/images/slack-message-example-228799226dec5760962b69c5e7816daf.png" />
</Frame>

<Frame caption="Slack text message">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/alerting/images/slack-test-message-alerting-f3d6a83c9a3468528ebc31d9e57c1a47.png" />
</Frame>


# HubSpot

Lago syncs billing data to HubSpot in real-time.

<Info>
  **PREMIUM ADD-ON** ✨

  This integration is only available to users with a specific paying add-on. Please
  **[contact us](mailto:hello@getlago.com)** to get access to HubSpot CRM integration.
</Info>

<Warning>
  This integration is a one-way sync, where Lago continuously syncs billing data to HubSpot in real time.
  Currently, it doesn’t support fetching information or taking actions from HubSpot back to Lago.
</Warning>

## Object mapping

<Info>
  As Lago needs to sync billing data to HubSpot custom objects, your HubSpot account needs to be on the **Sales Hub Enterprise** plan.
</Info>

<Frame caption="Lago to HubSpot object mapping">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/hubspot-crm-integration-objects-mapping.png" />
</Frame>

## Integration configuration

### oAuth connection

<Frame caption="Connect Lago to HubSpot through an oAuth connection">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/hubspot-integration-connect-screen.png" />
</Frame>

To fully integrate Lago with HubSpot, start by connecting your Lago instance to a new HubSpot connection. You can have an unlimited number of HubSpot connections. First, link your HubSpot account to Lago. Once connected, activate the specific syncs and actions required for your use case. This ensures that your Lago instance is properly configured to communicate with HubSpot, enabling seamless data synchronization and management.

1.  In Lago, navigate to **Integrations** > **HubSpot**;
2.  Create a **new HubSpot connection**;
3.  Assign a unique **name** and **code** to the connection;
4.  Select the **default targeted object** for Lago customers between HubSpot Contacts or Companies; and
5.  Use OAuth2 to grant access to the desired HubSpot account.

There you go, Lago is fully connected to HubSpot!

<Frame caption="Lago to HubSpot - oAuth connection flow">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/hubspot-integration-oauth-flow.png" />
</Frame>

### List of scopes

Here's a list of scopes you grant to Lago when connecting your HubSpot instance: `oauth`, `crm.objects.companies.read`, `crm.objects.companies.write`,
`crm.objects.custom.read`, `crm.objects.custom.write`, `crm.schemas.companies.read`, `crm.schemas.companies.write`, `crm.schemas.custom.read`,
`crm.objects.contacts.read`, `crm.objects.contacts.write`, `crm.schemas.contacts.read`, `crm.schemas.contacts.write` and `crm.schemas.custom.write`.

### Custom properties deployment

By connecting HubSpot to Lago, **custom properties are automatically added to both your HubSpot Companies and Contacts** (native objects).
These fields are used to sync customer data between HubSpot and Lago.

*   `lago_customer_id`: internal id of a Lago customer (unique);
*   `lago_customer_external_id`: your customer's external id in Lago;
*   `lago_billing_email`: your customer's billing email in Lago;
*   `lago_tax_identification_number`: your customer's tax identification number in Lago; and
*   `lago_customer_link`: the URL path to the related Lago customer.

<Frame caption="Custom properties deployed by Lago to HubSpot Companies and Contacts">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/hubspot-integration-custom-properties.png" />
</Frame>

<Info>
  Note that custom properties are deployed in the background the first time the connection is created.
</Info>

### Custom objects deployment

By connecting HubSpot to Lago, 2 custom objects are automatically deployed to your HubSpot instance: `LagoSubscriptions` and `LagoInvoices`.

<Info>
  Note that custom objects are deployed in the background the first time the connection is created. They are automatically tied to HubSpot Contacts or Companies.
</Info>

#### LagoSubscriptions

Here is the list of properties deployed with the `LagoSubscriptions` custom object:

| HubSpot Property Name            | Type        | Field Type | Has Unique Value |
| -------------------------------- | ----------- | ---------- | ---------------- |
| Lago Subscription Id             | string      | text       | true             |
| Lago External Subscription Id    | string      | text       | false            |
| Lago Subscription Name           | string      | text       | false            |
| Lago Subscription Plan Code      | string      | text       | false            |
| Lago Subscription Status         | string      | text       | false            |
| Lago Subscription Created At     | date        | date       | false            |
| Lago Subscription Started At     | date        | date       | false            |
| Lago Subscription Ending At      | date        | date       | false            |
| Lago Subscription At             | date        | date       | false            |
| Lago Subscription Terminated At  | date        | date       | false            |
| Lago Subscription Trial Ended At | date        | date       | false            |
| Lago Subscription Link           | string      | file       | false            |
| Lago Billing Time                | enumeration | radio      | false            |

#### LagoInvoices

Here is the list of properties deployed with the `LagoInvoices` custom object:

| HubSpot Property Name                 | Type   | Field Type      | Has Unique Value |
| ------------------------------------- | ------ | --------------- | ---------------- |
| Lago Invoice Id                       | string | text            | true             |
| Lago Invoice Number                   | string | text            | false            |
| Lago Invoice Issuing Date             | date   | date            | false            |
| Lago Invoice Payment Due Date         | date   | date            | false            |
| Lago Invoice Payment Overdue          | bool   | booleancheckbox | false            |
| Lago Invoice Type                     | string | text            | false            |
| Lago Invoice Status                   | string | text            | false            |
| Lago Invoice Payment Status           | string | text            | false            |
| Lago Invoice Currency                 | string | text            | false            |
| Lago Invoice Total Amount             | number | number          | false            |
| Lago Invoice Subtotal Excluding Taxes | number | number          | false            |
| Lago Invoice File URL                 | string | file            | false            |
| Lago Invoice Link                     | string | file            | false            |

## Sync data from Lago to HubSpot

### Sync customers to HubSpot

When you create or update a customer in Lago, the information is synced in real time to your HubSpot account. Please note the following:

*   If `customer.customer_type` in Lago is `company`, the data is synced as a HubSpot Company record.
*   If `customer.customer_type` in Lago is `individual`, the data is synced as a HubSpot Contact record.
*   If `customer.customer_type` is undefined, the data is synced using the default Customer Object set at the connection level.

<Frame caption="Customer syncs from Lago to HubSpot">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/hubspot-integration-customer-sync.png" />
</Frame>

<Frame caption="Example of a Company created by Lago">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/hubspot-integration-create-company.png" />
</Frame>

You can instruct Lago to automatically create a new Company or Contact in your HubSpot account, or link an existing one by pasting a HubSpot ID into the corresponding Lago customer record.

### Sync subscriptions to HubSpot

Whenever a Lago customer is linked to a HubSpot Contact or Company, **Lago Subscriptions are automatically synced in real-time with the `LagoSubscriptions` object in HubSpot**.
The subscription record is then automatically associated with the corresponding Contact or Company in HubSpot.

### Sync invoices to HubSpot

Whenever a Lago customer is linked to a HubSpot Contact or Company, **Lago Invoices are automatically synced in real-time with the `LagoInvoices` object in HubSpot**.
The invoice record is then automatically associated with the corresponding Contact or Company in HubSpot.


# Salesforce CPQ

Lago syncs billing data to Salesforce in real-time.

<Info>
  **PREMIUM ADD-ON** ✨

  This integration is only available to users with a specific paying add-on. Please
  **[contact us](mailto:hello@getlago.com)** to get access to Salesforce CPQ integration.
</Info>

<Info>
  This is extension package of the base package: Lago for Salesforce CRM. Base package must be installed to install CPQ package.
</Info>

## Object mapping

<Frame caption="Lago to Salesforce CPQ object mapping">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/lago-salesforce-cpq-object-mapping.png" />
</Frame>

## Pre-requisite:

*   Salesforce CPQ (> Summer '19)
*   Install Lago For Salesforce CRM Package [Lago Base Package](/integrations/crm/salesforce-crm)

## I. Integration configuration

### Install Salesforce CRM Package and complete Integration configuration step

*   [Integration configuration ](/integrations/crm/salesforce-crm#install-salesforce-crm-package)
*   [Establish and finalize connection](/integrations/crm/salesforce-crm#establish-and-finalize-connection)

### Install Salesforce CPQ Package

To gain premium access to our Salesforce Package application, please don't hesitate to contact us.
You can initiate the installation process **by clicking on the provided link**, which will direct you to the installation
page where you can follow step-by-step instructions for a seamless integration. If you have any questions or need assistance
during the installation, our dedicated support team is here to help you every step of the way.

<Frame caption="Install Lago Salesforce App package">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/lago-install-salesforce-cpq-package.png" />
</Frame>

To ensure a successful installation, please follow these steps:

1.  We recommend selecting the **"Install for all users"** option;
2.  Click on the **"Install" button**;
3.  Make sure to **check the box to grant access to these third-party websites**; and
4.  Once completed, you'll have **successfully installed** the Lago Salesforce App.

<Info>
  Please note that the installation process may take a few minutes to complete.
  However, rest assured that you will receive an email confirmation once the installation is finished.
</Info>

*

## II. Configuration to sync data

### Assign Permission:

Assign `Lago CPQ Permission` to users who needs to access Lago for Salesforce CPQ.

### Include Lago Fields in 'Quote Line Items editor' layout

Update the "Edit Line" which is available in Quote Layout to enter the details related to lago fieds in QuoteLine by following below steps:

1.  Go to Setup
2.  Click on Object manager
3.  Go to `Quote Line` object
4.  Click on \`field sets.
5.  Select edit 'Line Editor\` field set.
    6 Make sure following fields are available in field set:
    *   Lago Name
    *   Lago External Id
    *   Lago Billing Time
    *   Lago Start Date
    *   Lago End Date

## III. Actions from Salesforce to Lago

Beyond just syncing data from Lago to Salesforce, you can also initiate actions in Lago directly from Salesforce.
You can leverage Salesforce `Flows` to execute actions in Lago. Lago provides  customizable templates for creating subscription from Salesforce Accounts, directly assigning subscriptions to customers from Salesforce, creating one-off invoice from salesforce.

### Create customers [from Lago to Salesforce CRM](/integrations/crm/salesforce-crm#flow-lago-template-create-customer-in-lago-on-account-create)

### Create subscriptions (automation)

Assigning a plan to a customer, adjusting negotiated prices, and initiating the subscription upon accepting a quote represents a key action from Salesforce to Lago.

To assign a subscription and set prices in Lago directly from Salesforce, use the provided two flows via following Lago Flow templates.

#### Flow 1: `LagoCPQ Template - Quote Line After Insert`

This Flow is used to update Subscription External Id if it is null

1.  Log into your Salesforce instance;
2.  Access the Setup section via the settings gear icon in Salesforce;
3.  Find and select `Flows` under Process Automation in the sidebar;
4.  Locate and open the `LagoCPQ Template - Quote Line After Insert`;
5.  Click 'Save As' to create and save your own version of the template; and
6.  Do not forget to click the `Activate` button to activate your flow.

The default setting triggers plan assignment when Lago subscription external id is null You can customize this flow to suit your specific needs.

#### Flow 2: Pre-requisite from Lago to Salesforce CRM package: `Lago Template - Create Subscription in Lago on Subscription Creation/Update`

This Flow is used to create subscriptions in Lago from Salesforce

1.  Log into your Salesforce instance;
2.  Access the Setup section via the settings gear icon in Salesforce;
3.  Find and select `Flows` under Process Automation in the sidebar;
4.  Locate and open the `Lago Template - Create Subscription in Lago on Subscription Creation/Update`;
5.  Click 'Save As' to create and save your own version of the template; and
6.  Do not forget to click the `Activate` button to activate your flow.

The default setting triggers plan assignment when `SyncToLago` checkbox is checked. You can customize this flow to suit your specific needs.

#### Flow 3: `LagoCPQ Template - Create Lago SObject Records Using Quotes`

This Flow is used to create Lago subscriptions records in Salesforce when Quote status is changed to Approved

1.  Log into your Salesforce instance;
2.  Access the Setup section via the settings gear icon in Salesforce;
3.  Find and select `Flows` under Process Automation in the sidebar;
4.  Locate and open the `LagoCPQ Template - Create Lago SObject Records Using Quotes`;
5.  Click 'Save As' to create and save your own version of the template; and
6.  Do not forget to click the `Activate` button to activate your flow.

The default setting triggers plan assignment when Quote status is changed to Approved. You can customize this flow to suit your specific needs.

### Terminate Subscription

We can terminate the subscription from Salesforce to lago only if the subscription is already synced to lago(status is *active* or *pending*).

Go to Lago Subscription record in Salesforce, and check `Terminate Subscription` checkbox.

<Info>
  As soon as `Terminate Subscription` is checked it will terminate the subscription in Lago. It is handled from the backend via trigger.
</Info>

## Debugging & logs

To ensure seamless data synchronization between Lago and Salesforce, every action and data transfer is meticulously logged.
These logs are accessible directly through the Lago package for comprehensive debugging and analysis:

1.  Navigate to 'Lago Base Configuration': This is your starting point for accessing the debugging tools. and
2.  Access Logs: Click on the 'Logs' tab to view a detailed record of all activities.

You can refresh logs to keep your data current or delete unnecessary logs to maintain clarity and efficiency in the debugging process.
This approach aids in promptly identifying and resolving integration issues.


# Salesforce CRM

Lago syncs billing data to Salesforce in real-time.

<Info>
  **PREMIUM ADD-ON** ✨

  This integration is only available to users with a specific paying add-on. Please
  **[contact us](mailto:hello@getlago.com)** to get access to Salesforce CRM integration.
</Info>

## Object mapping

<Frame caption="Lago to Salesforce object mapping">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/lago-salesforce-object-mapping.png" />
</Frame>

## I. Integration configuration

### Install Salesforce CRM Package

To gain premium access to our Salesforce Package application, please don't hesitate to contact us.
You can initiate the installation process **by clicking on the provided link**, which will direct you to the installation
page where you can follow step-by-step instructions for a seamless integration. If you have any questions or need assistance
during the installation, our dedicated support team is here to help you every step of the way.

<Frame caption="Install Lago Salesforce App package">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/lago-install-salesforce-package.png" />
</Frame>

To ensure a successful installation, please follow these steps:

1.  We recommend selecting the **"Install for all users"** option;
2.  Click on the **"Install" button**;
3.  Make sure to **check the box to grant access to these third-party websites**; and
4.  Once completed, you'll have **successfully installed** the Lago Salesforce App.

<Info>
  Please note that the installation process may take a few minutes to complete.
  However, rest assured that you will receive an email confirmation once the installation is finished.
</Info>

### Webhook config: sync real-time data

After installation in Salesforce CRM, set up a webhook URL in Salesforce to receive real-time data from Lago.
This involves **configuring a new "Site" in Salesforce's setup section**.
Note that the four main actions described below should be performed by a Salesforce Admin and is only required during the initial setup.

<Steps titleSize="h3">
  <Step title="Access the Site section in Salesforce" titleSize="h3">
    1.  Click the gear icon in the upper right to access **Salesforce Setup**;
    2.  Search and navigate to the Sites section; and
    3.  Create a new Site (see picture below).

    <Frame caption="Create a new Site in Salesforce">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/create-new-site-salesforce.png" />
    </Frame>
  </Step>

  <Step title="Create a new Site in Salesforce" titleSize="h3">
    When creating a new site, follow these steps:

    1.  Set a unique **Site Label**;
    2.  Specify a unique **Site Name**;
    3.  Optionally, add a **Site Description**;
    4.  Ensure the **Site Contact** and **Default Record Owner** are filled;
    5.  Set the **Default Web Address** prefix to `getPushNotification`;
    6.  Choose `SiteLogin` as the **Active Site Home Page**; and
    7.  Don't forget to **save the new site**: and
    8.  **Activate the newly created site** by going to the Site Details and clicking the `Activate` button.

    <Frame caption="New site creation flow in Salesforce">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/new-site-creation-flow-salesforce.png" />
    </Frame>
  </Step>

  <Step title="Edit Public Access Settings in Salesforce" titleSize="h3">
    To edit Public Access Settings for your new Site:

    1.  Visit the site and click **Public Access Settings**;
    2.  In the **Enabled Apex Class Access** section, click "edit";
    3.  Add `LagoWebHookSubscriptionController` to **Enabled Apex Classes**; and
    4.  Save your changes.

    <Frame caption="Edit Salesforce's site Public Access Settings">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/edit-public-access-settings-salesforce.png" />
    </Frame>
  </Step>

  <Step title="Paste the Webhook URL into Your Lago App" titleSize="h3">
    To set up the webhook URL for real-time data syncing between Lago and Salesforce, follow these steps:

    1.  Return to your newly created site;
    2.  Locate the **Custom URLs** section;
    3.  Copy the **domain name** *(e.g., lago.my.salesforce-sites.com)*;
    4.  Add the `https://` prefix to this domain name (e.g., `https://lago.my.salesforce-sites.com`); and
    5.  Append `/services/apexrest/lago/api/Webhooks/incoming/pushDetails/` to the domain name (e.g., `https://lago.my.salesforce-sites.com/services/apexrest/lago/api/Webhooks/incoming/pushDetails/`).

    <Frame caption="Find Salesforce's site domain name">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/find-domain-url-salesforce.png" />
    </Frame>

    Now, go to your Lago app and past this webhook into the webhook’s settings:

    1.  Within Lago, navigate to **Developers**;
    2.  Visit the **Webhooks** tab;
    3.  Choose `HMAC` as the **mandatory signature type**;
    4.  Paste your Salesforce webhook URL; and
    5.  Save this webhook endpoint.

    Congratulations! You're ready to sync real-time data from Lago to Salesforce! 🎉

    <Frame caption="Paste Salesforce webhook URL to Lago">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/add-salesforce-webhook-url.gif" />
    </Frame>
  </Step>
</Steps>

### Establish and finalize connection

<Frame caption="Connect your Lago instance to Salesforce Lago App">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/salesforce-package-api-connection.gif" />
</Frame>

**Option 1: Configure a standard API Base URL**
To establish a connection between your Lago instance and the Salesforce Package, follow these steps:

1.  Access Salesforce and locate the **App Launcher**;
2.  Find and open the Lago app you recently installed;
3.  Within the Lago Base Configuration tab:

*   Provide your **Lago API Key** (located in Lago's Developer Section)
*   Enter your Lago **API base URL**. Do not insert the `api/v1` at the end of the URL. By default, the valid URL is `https://api.getlago.com/`.
    If you want to change the API base URL to another one (e.g., `https://api.eu.getlago.com/` or a custom self-hosted one), please follow option 2.
*   Enter lago app URL (**Front End Base URL**). By default, the valid URL is `https://app.getlago.com/` (it will be different for self-hosted).

4.  **"Save and validate"** your connection; and

*   If the **Lago API Key** is valid then only **Start Data Sync** button will be enabled.

5.  Click the **"Start Data Sync"** to finalize the connection between Lago and Salesforce.

<Warning>
  Please note that data synchronization is available only for Lago customers with an `external_salesforce_id` and an existing Salesforce Account.
</Warning>

**Option 2: Configure a custom API Base URL**
If you use your own Lago API base URL (self-hosting) or one for a different server instance,
you can customize it directly in Salesforce:

1.  Navigate to Salesforce's Setup;
2.  Search for and select Remote Site Settings;
3.  Find and access the remote site for the Lago App;
4.  Click the Edit button to modify the remote site's details;
5.  Update the Remote Site URL with your preferred URL; and
6.  Save the changes.

## II. Sync data from Lago to Salesforce

If your webhook endpoint is configured correctly, your **billing data will flow seamlessly in real-time**.

<Info>
  Please note that Subscriptions and Invoices will be created in Salesforce via webhooks seamlessly
</Info>

### Sync customers to Salesforce

To synchronize Lago Customer data with Salesforce Accounts (native object), ensure that your
Salesforce Account is created first, and that the Lago Customer's `external_salesforce_id` is explicitly populated.

1.  Begin by creating a new Account in Salesforce or accessing an existing one;
2.  Next, create a customer in Lago and populate the `external_salesforce_id` field for a Lago Customer with the Salesforce Account Id; and
3.  Finally, your Salesforce Account and Lago Customer are synchronized!

<Warning>
  Billing data will not sync unless these requirements are met.
  Lago does not create Salesforce Accounts.
  Before syncing billing data, you need to create or retrieve an existing Account in Salesforce
  and populate the Lago customer field called `external_salesforce_id`.
</Warning>

<Frame caption="Salesforce Account with Lago Customer information">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/lago-synced-account-salesforce.png" />
</Frame>

### Sync subscriptions to Salesforce

<Frame caption="Sync subscriptions data from Lago to Salesforce">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/sync-lago-subscriptions-salesforce.gif" />
</Frame>

Whenever a subscription is created for a Lago Customer, the subscription details will be automatically
synced in real-time with Salesforce using the `Lago Subscriptions` custom object.

Here is a list of Subscription fields that are automatically synced.
Note that this subcription is automatically linked to a Salesforce Account:

*   Subscription Id;
*   Subscription Name;
*   Subscription Start Date;
*   Subscription Status;
*   Subscription Termination Date (synced when the subscription is terminated);
*   Subscription Billing Time (either `calendar` or `anniversary`); and
*   Plan Code.

### Sync invoices to Salesforce

<Frame caption="Sync invoices data from Lago to Salesforce">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/sync-lago-invoices-salesforce.gif" />
</Frame>

Whenever an invoice is issued for a Lago Customer, the invoice details will be automatically
synced in real-time with Salesforce using the `Lago Invoices` custom object.

Here is a list of Subscription fields that are automatically synced:

*   Invoices Number;
*   Invoice Payment Status;
*   Invoice Type (`subscription` or `one-off`);
*   Invoice Issuing Date;
*   Invoice Amount;
*   Invoice File Url; and
*   Invoice Currency.

### Sync credit notes to Salesforce

Whenever a credit note is issued for a Lago Invoice, the credit note details will be automatically
synced in real-time with Salesforce using the `Lago CreditNotes` custom object.

### Sync Plans, Add-Ons to Salesforce

Plans and Add-ons are synced to Salesforce when we initially click on **Start Data Sync** from Lago Base Configuration page.

*   Plans are synced to `Lago Plans` object and `Product2` standard object. We also create a *price book entry* for all the products in `Standard Price Book` price book
*   Add-Ons are synced to `Lago Add-Ons` object and `Product2` standard object. We also create a *price book entry* for all the products in `Standard Price Book` price book.

### Schedule Sync from Lago To Salesforce

We also provide option to schedule the data sync from Lago to Salesforce.

*   `LagoSyncScheduleable` -- a schedulable class which helps us schedule either all the data or any one of them.
*   To schedule the sync of any *ONE* of the object:
    *   Create a new instance of class by passing any one of the following string: `CUSTOMER`, `SUBSCRIPTION`, `PLAN`, `ADDON`, `INVOICE`, `CREDITNOTE`
        *   Ex: To sync Plans from lago to Salesforce everyday at 1PM, execute below anonymous code in Anonymous window in Developer Console. ([click here to learn more about CRON expression](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_scheduler.htm))
            ```
            //Create a new instance. Pass 'PLAN' in brackets.
            lago.LagoSyncScheduleable syncPlan = new lago.LagoSyncScheduleable('PLAN');
            //CRON expression to schedule a job everyday at 1 PM
            String schedule_cron = '0 0 13 * * ?';
            //schedule(name, cron_expression, class_instance)
            System.schedule('Sync Lago Plan', schedule_cron, syncPlan);
            ```
*   To schedule the sync of  *ALL* the objects:
    *   create a new instance of class by passing `true`
        *   Ex: To sync **all** objects from lago to Salesforce everyday at 1PM, execute below anonymous code in Anonymous window in Developer Console. ([click here to learn more about CRON expression](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_scheduler.htm))
            ```
            //Create a new instance. Pass true in brackets.
            lago.LagoSyncScheduleable syncAll = new lago.LagoSyncScheduleable(true);
            //CRON expression to schedule a job everyday at 1 PM
            String schedule_cron = '0 0 13 * * ?';
            //schedule(name, cron_expression, class_instance)
            System.schedule('Sync Lago all', schedule_cron, syncAll);
            ```

## III. Actions from Salesforce to Lago

Beyond just syncing data from Lago to Salesforce, you can also initiate actions in Lago directly from Salesforce.
You can leverage Salesforce `Flows` to execute actions in Lago. Lago provides several customizable templates for creating customers from Salesforce Accounts, directly assigning subscriptions to customers from Salesforce, creating one-off invoice from salesforce.

### Create customers

#### Flow: `Lago Template - Create Customer in Lago on Account Create`

<Frame caption="Use Lago template to create a customer on Account creation">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/lago-salesforce-flows-template.png" />
</Frame>

To create a customer in Lago upon the creation of a Salesforce Account, utilize the Flow template provided by Lago.

1.  Log into your Salesforce instance;
2.  Access the Setup section via the settings wheel icon in Salesforce;
3.  Find and select `Flows` under Process Automation in the sidebar;
4.  Locate and open the `Lago Template - Create Customer in Lago on Account Create`;
5.  Click 'Save As' to create and save your own version of the template; and
6.  Do not forget to click the `Activate` button to activate your flow.

You have the **flexibility to modify various aspects of this flow, including the trigger conditions and field mappings**.
By default, the action is initiated when a Lago ID is absent. Additionally, you can customize how fields are mapped from your Salesforce instance to Lago.

<Frame caption="Customize the flow">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/account-customer-flow.gif" />
</Frame>

### Create subscriptions (automation)

Assigning a plan to a customer, adjusting negotiated prices, and initiating the subscription upon winning an opportunity represents a key action from Salesforce to Lago.
This enables sales teams to remain within Salesforce, their primary tool, and activate billing processes directly, without the need to switch platforms.

To assign a subscription and set prices in Lago directly from Salesforce, use the provided two flows via following Lago Flow templates.

#### Flow 1: `Lago Template - Create Lago SObject Records`

This Flow is used to create intermediate records in Lago Objects - `Lago Subscription`

1.  Log into your Salesforce instance;
2.  Access the Setup section via the settings gear icon in Salesforce;
3.  Find and select `Flows` under Process Automation in the sidebar;
4.  Locate and open the `Lago Template - Create Lago SObject Records`;
5.  Click 'Save As' to create and save your own version of the template; and
6.  Do not forget to click the `Activate` button to activate your flow.

<Steps>
  <Step title="Validate the flow">
    The default setting triggers plan assignment when a Salesforce Account links to a Lago customer and the **opportunity status changes to closed-won**.
    You can customize this flow to suit your specific needs. Moreover, you have the option to adjust the subscription fields and subscription charges fields being synchronized from Salesforce to Lago.

    <Frame caption="Customize the flow">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/sync-subscriptions-salesforce-lago-flow.gif" />
    </Frame>
  </Step>

  <Step title="Assign subscription and override prices">
    1.  Create an opportunity by assigning an expected closed date and a stage;
    2.  Add a Lago plan to this opportunity **as a product** (Salesforce will automatically retrieve all plans from Lago in `Standard Price Book`);
    3.  Specify `1` for the quantity of the plan;
    4.  Use the custom UI to either assign this plan directly or to override prices; and
    5.  Click on 'Lago Override Plan' to finalize the subscription assignment.

    <Info>
      By default, the lago subscription record in salesforce is created when the opportunity is `closed-won`. You can assign multiple subscriptions for the same opportunity.
    </Info>
  </Step>
</Steps>

#### Flow 2: `Lago Template - Create Subscription in Lago on Subscription Creation/Update`

This Flow is used to create subscriptions in Lago from Salesforce

1.  Log into your Salesforce instance;
2.  Access the Setup section via the settings gear icon in Salesforce;
3.  Find and select `Flows` under Process Automation in the sidebar;
4.  Locate and open the `Lago Template - Create Subscription in Lago on Subscription Creation/Update`;
5.  Click 'Save As' to create and save your own version of the template; and
6.  Do not forget to click the `Activate` button to activate your flow.

The default setting triggers plan assignment when `SyncToLago` checkbox is checked. You can customize this flow to suit your specific needs.

### Create subscriptions (lago native UI)

We also have option to create subscriptions in Lago directly from Salesforce using Lago's create subscription screen.

1.  Log into your Salesforce instance;
2.  Access the setup section via the settings gear icon in Salesforce;
3.  Go to Object manager and find and open account object;
4.  Go to page layout (or Lightning record page) depending on what you are using, and open the page layout in which you'd like to add the button to create subscription.
5.  Add the button `Lago Subscription`
6.  Save the page layout or lightning record page.

Open any account which has `lago_id` populated. Click on `Lago Subscription` button; it will pop-up Lago Screen (make sure you've entered correct `Front End URL` in Lago Base Configuration page); enter correct username and password. Save. A new subscription will be directly created in Lago. And, if Webhooks are configured correctly, it will also create `Lago Subscription` record in Salesforce.

<Frame caption="Lago Subscription from SF (iframe)">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/salesforce-lago-subscription-iframe.gif" />
</Frame>

<Info>
  We can add a new button ***Lago Subscription*** on *Account* page or *Opportunity* page
  A new Lago Subscription record will be created via webhooks (if configured).
  And after 1 minute another callout will be made to sync Charges.
</Info>

### Terminate Subscription

We can terminate the subscription from Salesforce to lago only if the subscription is already synced to lago(status is *active* or *pending*).

Go to Lago Subscription record in Salesforce, and check `Terminate Subscription` checkbox.

<Info>
  As soon as `Terminate Subscription` is checked it will terminate the subscription in Lago. It is handled from the backend via trigger.
</Info>

### Create one-off invoice

This enables sales team to create one-off invoice in lago from Salesforce.
Right from the opportunity record we add products which are related to `Lago Add-ons`, specify the quantity, description and amount.

To create one-off invoice and set prices in Lago directly from Salesforce, use the provided two flows via following Lago Flow templates.

#### Flow 1: [`Lago Template - Create Lago SObject Records`](/integrations/crm/salesforce-crm#flow-1-lago-template-create-lago-sobject-records)

The same flow as we created above to create subscription - is also used to create intermediate records in Lago Objects - `Lago Invoice`

#### Flow 2: `Lago Template - Generate Invoice in Lago On Lago Invoice Field Update`

This Flow is used to create one-off invoice in Lago from Salesforce

1.  Log into your Salesforce instance;
2.  Access the Setup section via the settings gear icon in Salesforce;
3.  Find and select `Flows` under Process Automation in the sidebar;
4.  Locate and open the `Lago Template - Generate Invoice in Lago On Lago Invoice Field Update`;
5.  Click 'Save As' to create and save your own version of the template; and
6.  Do not forget to click the `Activate` button to activate your flow.

The default setting triggers create invoice when `SyncToLago` checkbox is checked. You can customize this flow to suit your specific needs.

### Create one-off invoice (lago native UI)

We also have option to create one off invoice in Lago directly from Salesforce using Lago's create invoice screen.

1.  Log into your Salesforce instance;
2.  Access the setup section via the settings gear icon in Salesforce;
3.  Go to Object manager and find and open Account object or Opportunity;
4.  Go to page layout (or Lightning record page) depending on what you are using, and open the page layout in which you'd like to add the button to create Invoice.
5.  Add the button `Lago Invoice`
6.  Save the page layout or lightning record page.

Open any account which has `lago_id` populated. Click on `Lago Invoice` button; it will pop-up Lago Screen (make sure you've entered correct `Front End URL` in Lago Base Configuration page); enter correct username and password. Save. A new Invoice will be directly created in Lago. And, if Webhooks are configured correctly, it will also create `Lago Invoice` record in Salesforce.

<Frame caption="Lago Invoice from SF (iframe)">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/salesforce-lago-invoice-iframe.gif" />
</Frame>

<Info>
  We can add a new button ***Lago Invoice*** on *Account* page or *Opportunity* page
  A new Lago Invoice record will be created via webhooks (if configured).
  After 1 minute another callout will be made to sync invoice line items (add ons).
</Info>

### Get Invoice pdf

Now we can also get invoice pdf directly directly from Salesforce.

1.  Go to Lago Invoice
2.  Open any Invoice which is already synced.
3.  Click `Get Invoice pdf` > it will open PDF in a new tab.

## Debugging & logs

To ensure seamless data synchronization between Lago and Salesforce, every action and data transfer is meticulously logged.
These logs are accessible directly through the Lago package for comprehensive debugging and analysis:

1.  Navigate to 'Lago Base Configuration': This is your starting point for accessing the debugging tools. and
2.  Access Logs: Click on the 'Logs' tab to view a detailed record of all activities.

You can refresh logs to keep your data current or delete unnecessary logs to maintain clarity and efficiency in the debugging process.
This approach aids in promptly identifying and resolving integration issues.


# Airbyte (ETL)



Airbyte is an open-source **data integration platform** used as an ETL. With this integration, you can connect Lago billing data to any warehouses.

## Destinations

You can push Lago billing data to destinations such as Snowflake, BigQuery, Redshift, S3 buckets or Azure, for instance.
The entire list of data destinations enabled by Airbyte is listed on their [destinations documentation](https://docs.airbyte.com/integrations/destinations/).

## Data available for extraction

With Airbyte's native integration of Lago, you can push the following billing data to warehouses:

*   billable\_metrics
*   plans
*   coupons
*   add\_ons
*   invoices
*   customers
*   subscriptions

<Warning>
  At present this connector **only supports full refresh syncs** meaning that each time you use the connector it will sync all available records from scratch. Please use cautiously if you expect your API to have a lot of records.
</Warning>

Find the full documentation of [Airbyte's native Lago integration](https://docs.airbyte.com/integrations/sources/getlago/).

## 1. Connect Lago to Airbyte

First of all, you simply need to bring your Lago private API key.
In airbyte:

*   Go to **Sources**;
*   Select getLago as a source of data; and
*   Paste your Lago private API key.

<Frame caption="Lago data source in Airbyte">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/lago-airbyte-source-e56dc399ab95d5f523683b5c62f3b3e5.png" />
</Frame>

## 2. Select a destination

You can select any of the data destinations available in Airbyte. It could be a warehouse (BigQuery, Redshift, Snowflake...) or a file storage tool (S3, for instance). Please find here the entire list of [data destinations available in Airbyte](https://docs.airbyte.com/integrations/destinations/).

<Frame caption="Destination in Airbyte">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/destination-airbyte-52676d7f8ffd515d98027fbe02eb2b05.png" />
</Frame>

## 3. Sync billing data

In the following example, we connected Lago billing data to Snowflake data warehouse. Obviously, you can select another destination if needed.

1.  Create a **data sync** between Lago source and your destination;
2.  Define a **sync frequency**; and
3.  Activate the sync in Airbyte between Lago source and your destination.

This action will populate Lago billing data into a warehouse (Snowflake in our example).

<Frame caption="Lago data in Snowflake">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/lago-data-snowflake-ec9a012ccb50edc332d6750de7246076.png" />
</Frame>

## 4. Query Lago billing data

Once the data has been populated in your destination, a warehouse in our example, you can easily query your billing data. Here is a query calculating your monthly revenue with Lago:

<Frame caption="Query in snowflake">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/data/images/example-billing-query-snowflake-a4cf76e6bca92363215567a0e4e51f06.png" />
</Frame>


# Oso



[Oso](https://www.osohq.com/)  is an authorization-as-a-service provider partnering with Lago to offer entitlements. You can use either the open-source version (available on [Github](https://github.com/osohq/oso)) or the cloud-hosted version. To create entitlements with Lago, you must open an account on Oso.

Oso offers a suitable solution for Entitlements. For more information, please refer to [Oso's documentation](https://www.osohq.com/docs/guides/model/entitlements).

## Define available features and plan's quota

First, define the available features for each plan. For instance, the Basic plan has a limited set of features, while the Premium plan offers the full range.

In addition to this, you can use Lago to bill metering and overage. This information can then be passed directly to Oso's `plan_quota` and `quota_used` to limit usage for a specific feature.

## Example

[Oso's documentation](https://www.osohq.com/docs/guides/model/entitlements) explains the following example of entitlements properly.

```ruby
actor User { }
 
resource Organization {
    roles = ["admin", "member"];
    permissions = ["create_repository"];
 
    "member" if "admin";
}
 
 
resource Plan { 
    roles = ["subscriber"];
    relations = { subscribed_organization: Organization };
    
    "subscriber" if role on "subscribed_organization";
}
 
resource Feature {
    relations = { plan: Plan };
}
 
declare plan_quota(Plan, Feature, Integer);
declare quota_used(Organization, Feature, Integer);
 
plan_quota(Plan{"pro"}, Feature{"repository"}, 10);
plan_quota(Plan{"basic"}, Feature{"repository"}, 0);
 
has_quota_remaining(org: Organization, feature: Feature) if
    has_quota(org, feature, quota) and
    quota_used(org, feature, used) and
    used < quota;
 
has_quota(org: Organization, feature: Feature, quota: Integer) if
    plan matches Plan and
    has_relation(plan, "subscribed", org) and
    plan_quota(plan, feature, quota);
 
 
has_permission(user: User, "create_repository", org: Organization) if
    has_role(user, "member", org) and
    has_quota_remaining(org, Feature{"repository"});
 
 
 
test "members can create repositorys if they have quota" {
    setup {
        quota_used(Organization{"apple"}, Feature{"repository"}, 5);
        quota_used(Organization{"netflix"}, Feature{"repository"}, 10);
        quota_used(Organization{"amazon"}, Feature{"repository"}, 0);
        has_relation(Plan{"pro"}, "subscribed", Organization{"apple"});
        has_relation(Plan{"pro"}, "subscribed", Organization{"netflix"});
        has_relation(Plan{"basic"}, "subscribed", Organization{"amazon"});
        has_role(User{"alice"}, "member", Organization{"apple"});
        has_role(User{"bob"}, "member", Organization{"netflix"});
        has_role(User{"charlie"}, "member", Organization{"amazon"});
    }
    assert has_quota_remaining(Organization{"apple"}, Feature{"repository"});
    # Apple has quota remaining, so all good
    assert allow(User{"alice"}, "create_repository", Organization{"apple"});
    # Netflix has used all quota 
    assert_not allow(User{"bob"}, "create_repository", Organization{"netflix"});
    # Amazon doesn't have any quota left
    assert_not allow(User{"charlie"}, "create_repository", Organization{"amazon"});
}
```


# Introduction

Find all Lago native integrations with third party tools, whether it's related to payment providers, alerting systems or data integrations.

## Usage tracking integrations

<CardGroup cols={2}>
  <Card
    title="Segment.com"
    iconType="brand"
    icon={
     <svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
       <rect width="32" height="32" rx="8" fill="#49B881"/>
       <path d="M17.9688 18.6368H8.76831C8.34574 18.6368 8 18.3015 8 17.8916C8 17.4818 8.34574 17.1465 8.76831 17.1465H17.9688C18.3914 17.1465 18.7371 17.4818 18.7371 17.8916C18.7371 18.3015 18.3914 18.6368 17.9688 18.6368Z" fill="white"/>
       <path d="M16.0096 23.2001C15.2605 23.2001 14.5114 23.0884 13.8007 22.8835C13.3974 22.7531 13.1669 22.3432 13.3013 21.952C13.4358 21.5608 13.8583 21.3373 14.2617 21.4677C14.8187 21.6353 15.4142 21.7285 16.0096 21.7285C18.6219 21.7285 20.8884 20.1078 21.6375 17.686C21.7527 17.2948 22.1945 17.0713 22.5978 17.1831C23.0012 17.2948 23.2317 17.7233 23.1164 18.1145C22.1369 21.151 19.2941 23.2001 16.0096 23.2001Z" fill="white"/>
       <path d="M23.2317 14.8555H14.0312C13.6087 14.8555 13.2629 14.5202 13.2629 14.1104C13.2629 13.7006 13.6087 13.3652 14.0312 13.3652H23.2317C23.6543 13.3652 24 13.7006 24 14.1104C24 14.5202 23.6543 14.8555 23.2317 14.8555Z" fill="white"/>
       <path d="M9.63265 14.8551C9.55582 14.8551 9.47899 14.8365 9.40216 14.8179C8.99879 14.7061 8.7683 14.2776 8.88355 13.8864C9.86314 10.8499 12.7059 8.80078 16.0096 8.80078C16.7587 8.80078 17.5078 8.91255 18.2185 9.11747C18.6218 9.24787 18.8523 9.6577 18.7179 10.0489C18.5834 10.4401 18.1609 10.6637 17.7575 10.5333C17.2005 10.3656 16.605 10.2724 16.0096 10.2724C13.3974 10.2724 11.1308 11.8931 10.3817 14.3149C10.2665 14.6502 9.95918 14.8551 9.63265 14.8551Z" fill="white"/>
       <path d="M20.5618 12.0235C20.9861 12.0235 21.3301 11.6899 21.3301 11.2784C21.3301 10.8668 20.9861 10.5332 20.5618 10.5332C20.1375 10.5332 19.7935 10.8668 19.7935 11.2784C19.7935 11.6899 20.1375 12.0235 20.5618 12.0235Z" fill="white"/>
       <path d="M11.4382 21.4864C11.8625 21.4864 12.2065 21.1528 12.2065 20.7412C12.2065 20.3297 11.8625 19.9961 11.4382 19.9961C11.0138 19.9961 10.6699 20.3297 10.6699 20.7412C10.6699 21.1528 11.0138 21.4864 11.4382 21.4864Z" fill="white"/>
     </svg>
    }
    href="/integrations/usage/segment"
  >
    Segment is used to track and ingest events that can be sent to Lago as
    usage.
  </Card>

  <Card
    title="Hightouch"
    icon={
     <svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
       <rect width="32" height="32" rx="8" fill="#4FC26B"/>
       <g clip-path="url(#clip0_4694_561)">
       <path d="M23.7159 19.0013H12.9987V8.28307C12.9987 8.12656 13.1253 8 13.2818 8H23.7169C23.8734 8 24 8.12656 24 8.28307V18.7182C23.999 18.8747 23.8725 19.0013 23.7159 19.0013Z" fill="white"/>
       <path d="M12.7157 24.0007H8.28307C8.12656 24.0007 8 23.8741 8 23.7176V19.285C8 19.1285 8.12656 19.002 8.28307 19.002H12.9987V23.7176C12.9987 23.8741 12.8722 24.0007 12.7157 24.0007Z" fill="white"/>
       </g>
       <defs>
       <clipPath id="clip0_4694_561">
       <rect width="16" height="16" fill="white" transform="translate(8 8)"/>
       </clipPath>
       </defs>
     </svg>
    }
    href="/integrations/usage/hightouch"
  >
    Reverse-ETL helping you sync data from any sources (database, warehouses,
    spreadsheet...) to Lago.
  </Card>
</CardGroup>

## Payments integrations

<CardGroup cols={2}>
  <Card
    title="GoCardless"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#F1F252" />
       <g clip-path="url(#clip0_4694_575)">
         <path
           d="M8 16.3853C8.00653 11.7542 11.5828 8 16.276 8C18.0772 8 19.0896 8.2923 19.0896 8.2923L22.0812 14.3849L22.0551 14.411L18.2013 12.1265C15.969 10.794 14.3458 10.1016 13.0263 10.1555C11.6334 10.1816 10.7957 11.3002 10.7957 12.925C10.8463 17.0777 14.803 22.1905 18.7255 22.1905C20.3307 22.1905 21.1651 21.6745 21.655 21.0507L15.8351 14.6821V14.6544H23.822C23.9314 15.2259 23.9918 15.804 24 16.3853C24 21.0458 20.4254 24.8 16.0114 24.8C11.5975 24.8 8 21.0458 8 16.3853Z"
           fill="#1C1B18"
         />
       </g>
       <defs>
         <clipPath id="clip0_4694_575">
           <rect
             width="16"
             height="16.8"
             fill="white"
             transform="translate(8 8)"
           />
         </clipPath>
       </defs>
     </svg>
    }
    href="/integrations/payments/gocardless-integration"
  >
    GoCardless is the global leader of direct debits bank payments.
  </Card>

  <Card
    title="Stripe Payments"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#6772E5" />
       <path
         d="M14.8624 12.7648C14.8624 12.0792 15.4268 11.8154 16.3617 11.8154C17.7021 11.8154 19.3953 12.2199 20.7358 12.9407V8.80877C19.2719 8.22859 17.8256 8 16.3617 8C12.7811 8 10.4 9.86379 10.4 12.976C10.4 17.8286 17.1023 17.055 17.1023 19.1474C17.1023 19.9561 16.3969 20.2199 15.4092 20.2199C13.9453 20.2199 12.0756 19.622 10.594 18.8132V22.9979C12.2343 23.7012 13.8923 24 15.4092 24C19.0778 24 21.6 22.1891 21.6 19.0418C21.5824 13.8023 14.8624 14.7341 14.8624 12.7648Z"
         fill="white"
       />
     </svg>
    }
    href="/integrations/payments/stripe-integration"
  >
    Stripe is a suite of APIs powering online payment processing, especially
    card payments.
  </Card>

  <Card
    title="Adyen"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#0ABF53" />
       <path
         fill-rule="evenodd"
         clip-rule="evenodd"
         d="M24 11.1908V24H11.209C9.44433 24 8 22.5536 8 20.7864V17.2051C8 15.4378 9.44433 13.9915 11.209 13.9915H14.6705V19.0877C14.6705 19.5924 15.0828 20.0058 15.5875 20.0058H17.3294V12.9123C17.3294 12.4076 16.9171 11.9942 16.4125 11.9942H8.22924V8H20.791C22.5563 8 24 9.44635 24 11.1908Z"
         fill="white"
       />
     </svg>
    }
    href="/integrations/payments/adyen-integration"
  >
    Adyen is an omnichannel payment processing company providing multiple ways
    to accept payments.
  </Card>
</CardGroup>

## Accounting integrations

{" "}

<CardGroup cols={2}>
  <Card
    title="NetSuite"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="black" />
       <path
         d="M25.1739 14.8219C24.7469 14.8219 24.3849 14.5342 24.2736 14.1443H26.6404L26.9653 13.6339H24.2736C24.3849 13.244 24.7469 12.9563 25.1739 12.9563H26.7982L27.1231 12.4457H25.1367C24.3384 12.4457 23.698 13.0956 23.698 13.8845C23.698 14.6828 24.3477 15.3232 25.1367 15.3232H26.8447L27.1694 14.8127H25.1739M18.398 15.3232H20.1152L20.44 14.8127H18.4445C17.9246 14.8127 17.5069 14.395 17.5069 13.8845C17.5069 13.3647 17.9246 12.9563 18.4445 12.9563H20.0688L20.3937 12.4457H18.4074C17.609 12.4457 16.9594 13.0956 16.9594 13.8845C16.9594 14.6828 17.609 15.3232 18.398 15.3232ZM7.88155 14.8219H6.27578C5.76533 14.8219 5.3476 14.4043 5.3476 13.8938C5.3476 13.374 5.76533 12.9656 6.27578 12.9656H7.87226C8.392 12.9656 8.80973 13.3832 8.80973 13.8938C8.80973 14.4043 8.392 14.8219 7.88155 14.8219ZM6.23861 15.3232H7.90943C8.70762 15.3232 9.34805 14.6828 9.34805 13.8845C9.34805 13.0863 8.70762 12.4457 7.90943 12.4457H6.23861C5.44971 12.4457 4.79999 13.0956 4.79999 13.8845C4.79999 14.6828 5.44971 15.3232 6.23861 15.3232ZM12.077 14.395C12.6153 14.395 13.0516 13.9588 13.0516 13.4204C13.0516 12.882 12.6153 12.4457 12.077 12.4457H9.65438V15.3232H10.2114V12.9563H12.04C12.2998 12.9563 12.5039 13.1605 12.5039 13.4204C12.5039 13.6803 12.2998 13.8845 12.04 13.8845H10.4804L12.1328 15.3232H12.9403L11.8263 14.3857H12.077M21.2383 14.8219V12.4457H20.6814V15.054C20.6814 15.1283 20.7094 15.1932 20.7649 15.249C20.8206 15.3047 20.8948 15.3325 20.9691 15.3325H23.4939L23.8187 14.8219H21.2383ZM14.4625 14.3115H15.9383L15.1587 13.0491L13.7199 15.3232H13.0608L14.8059 12.5943C14.8801 12.4829 15.0101 12.418 15.1494 12.418C15.2886 12.418 15.4093 12.4829 15.4835 12.5943L17.2377 15.3325H16.5881L16.2818 14.8219H14.7874L14.4625 14.3115Z"
         fill="white"
       />
       <path
         d="M5.06934 17.0605H5.80252L6.69323 18.9262V17.0605H7.16726V19.4365H6.47037L5.55208 17.4591V19.4271H5.06934V17.0605Z"
         fill="white"
       />
       <path
         d="M7.70514 17.0605H9.29274V17.4504H8.21547V18.0166H9.22741V18.4064H8.21547V19.0467H9.32976V19.4365H7.70514V17.0605Z"
         fill="white"
       />
       <path
         d="M10.3134 17.4504H9.60779V17.0605H11.5388V17.4504H10.8332V19.4365H10.3228V17.4504H10.3134Z"
         fill="white"
       />
       <path
         d="M12.1513 18.74C12.1605 18.9071 12.1791 19.2134 12.7266 19.2134C13.2186 19.2134 13.2836 18.9071 13.2836 18.7865C13.2836 18.5173 13.0702 18.4709 12.736 18.3874C12.374 18.2945 12.2163 18.2574 12.0955 18.1738C11.9007 18.0439 11.8449 17.8675 11.8449 17.7098C11.8449 17.2271 12.2998 17.0137 12.7453 17.0137C12.9031 17.0137 13.2186 17.0414 13.4136 17.2457C13.5435 17.3942 13.5528 17.552 13.5621 17.6541H13.2186C13.2001 17.357 12.9494 17.292 12.7175 17.292C12.3926 17.292 12.1883 17.4406 12.1883 17.6726C12.1883 17.8861 12.3276 17.951 12.6153 18.0254C13.1815 18.1738 13.2466 18.1831 13.3858 18.2759C13.6086 18.4245 13.6179 18.6472 13.6179 18.7493C13.6179 19.167 13.2929 19.4919 12.6803 19.4919C12.5039 19.4919 12.1328 19.4641 11.9471 19.2227C11.8079 19.0464 11.8079 18.8607 11.8079 18.74H12.1513Z"
         fill="white"
       />
       <path
         d="M14.4718 17.0605V18.527C14.4718 18.7777 14.5274 18.889 14.5738 18.9541C14.7224 19.149 14.9544 19.1861 15.1122 19.1861C15.7527 19.1861 15.7527 18.6849 15.7527 18.5086V17.0605H16.0682V18.527C16.0682 18.657 16.0682 18.9169 15.8733 19.1582C15.6413 19.4553 15.2793 19.4831 15.1029 19.4831C14.8801 19.4831 14.4811 19.4182 14.2676 19.1026C14.1933 19.0004 14.1283 18.8612 14.1283 18.5086V17.0605H14.4718Z"
         fill="white"
       />
       <path
         d="M16.7552 19.4365H17.0797V17.0605H16.7552V19.4365Z"
         fill="white"
       />
       <path
         d="M18.361 19.4365V17.3386H17.5625V17.0605H19.4746V17.3386H18.6768V19.4365H18.361Z"
         fill="white"
       />
       <path
         d="M19.8738 17.0605H21.3591V17.3386H20.1991V18.0812H21.3032V18.36H20.1991V19.149H21.3867V19.4365H19.8738V17.0605Z"
         fill="white"
       />
     </svg>
    }
    href="/integrations/accounting/netsuite"
  >
    NetSuite is the leading integrated cloud business software for business
    accounting.
  </Card>

  <Card
    title="Xero"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#00B9EA" />
       <path
         fill-rule="evenodd"
         clip-rule="evenodd"
         d="M17.1815 16.0575C17.3085 15.9003 17.3564 15.6947 17.3156 15.478C17.1506 14.6924 16.7255 14.0632 16.0871 13.6582C15.6486 13.3781 15.1368 13.2299 14.6072 13.2299C14.0226 13.2299 13.4661 13.4068 12.9979 13.7409C12.2657 14.2637 11.8287 15.1183 11.8287 16.026C11.8287 16.2541 11.8568 16.4803 11.9123 16.6985C12.1937 17.8044 13.1396 18.6404 14.2668 18.7795C14.3757 18.7925 14.4849 18.7992 14.591 18.7992C14.8166 18.7992 15.0363 18.7705 15.2623 18.7114C15.5559 18.6404 15.8354 18.5211 16.0938 18.3564C16.3376 18.1976 16.5624 17.9837 16.7987 17.685L16.8142 17.6689C16.8929 17.5704 16.9294 17.4435 16.9143 17.321C16.9009 17.2115 16.8486 17.1169 16.7675 17.0547C16.6903 16.9952 16.5989 16.9621 16.509 16.9621C16.4192 16.9621 16.2937 16.994 16.1777 17.1457L16.1686 17.1579C16.1302 17.2091 16.0907 17.2623 16.0451 17.3147C15.8888 17.4908 15.7095 17.6362 15.512 17.7461C15.2294 17.8974 14.9239 17.9754 14.6048 17.9778C13.6027 17.9667 12.9892 17.2966 12.7494 16.6745C12.7118 16.5626 12.6848 16.4602 12.6674 16.3652C12.6674 16.3558 12.6662 16.3455 12.6659 16.3357L16.5458 16.3349C16.8154 16.329 17.041 16.2301 17.1815 16.0567V16.0575ZM12.6963 15.5276C12.9176 14.6561 13.6973 14.0478 14.593 14.0478C15.4887 14.0478 16.2696 14.6546 16.4916 15.5276H12.6959H12.6963ZM23.5399 15.9775C23.5399 16.368 23.2237 16.6855 22.835 16.6855C22.4463 16.6855 22.1285 16.368 22.1285 15.9775C22.1285 15.5871 22.4455 15.27 22.835 15.27C23.2245 15.27 23.5399 15.5875 23.5399 15.9775ZM19.8563 14.0675C19.838 14.0675 19.7672 14.0679 19.7011 14.0758C18.9028 14.1751 18.8232 14.562 18.8232 15.4874V18.3442C18.8232 18.5656 18.6439 18.7456 18.4235 18.7456C18.203 18.7456 18.0253 18.5656 18.0237 18.3442L18.0225 13.6992C18.0241 13.4746 18.1999 13.2989 18.4231 13.2989C18.596 13.2989 18.7496 13.4131 18.8023 13.5759C19.0765 13.3749 19.4019 13.269 19.7458 13.269L19.859 13.2705C20.0807 13.2705 20.2615 13.4514 20.2615 13.6736C20.2615 13.8958 20.091 14.0581 19.8559 14.0668L19.8563 14.0675ZM11.8034 18.0936C11.879 18.1704 11.9206 18.2709 11.9206 18.3773C11.9206 18.5999 11.7401 18.7807 11.518 18.7807C11.4104 18.7807 11.3071 18.7358 11.2279 18.6538L9.1603 16.5795L7.08356 18.6637C7.00599 18.7385 6.90545 18.7799 6.80057 18.7799C6.57972 18.7799 6.40002 18.5995 6.40002 18.3773C6.40002 18.2673 6.44396 18.1645 6.52391 18.0881L8.59273 16.0059L6.52074 13.9265C6.44277 13.8489 6.40002 13.7465 6.40002 13.6389C6.40002 13.4171 6.57972 13.2363 6.80057 13.2363C6.90743 13.2363 7.00757 13.2776 7.08356 13.3525L9.16228 15.4323L11.2331 13.3564C11.3095 13.2788 11.4108 13.2363 11.518 13.2363C11.7401 13.2363 11.9206 13.4167 11.9206 13.6389C11.9206 13.7465 11.8786 13.8469 11.803 13.9214L9.73262 16.0079L11.8034 18.094V18.0936ZM22.8346 13.1992C21.3088 13.1992 20.0676 14.4458 20.0676 15.9775C20.0676 17.5093 21.3088 18.7555 22.8346 18.7555C24.3604 18.7555 25.6 17.5093 25.6 15.9775C25.6 14.4458 24.3592 13.1992 22.8346 13.1992ZM22.8346 17.9246C21.7648 17.9246 20.8948 17.0511 20.8948 15.9779C20.8948 14.9047 21.7652 14.0289 22.8346 14.0289C23.904 14.0289 24.7724 14.9032 24.7724 15.9779C24.7724 17.0527 23.9033 17.9246 22.8346 17.9246Z"
         fill="white"
       />
     </svg>
    }
    href="/integrations/accounting/xero"
  >
    Xero is a cloud-based accounting software for small businesses.
  </Card>

  <Card
    title="QuickBooks (Beta)"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#2CA01C" />
       <path
         d="M12.3077 11.7279C9.92892 11.7279 8 13.6412 8 16.0008C8 18.3603 9.92533 20.2701 12.3077 20.2701H12.9231V18.6852H12.3077C10.8142 18.6852 9.60144 17.4822 9.60144 16.0008C9.60144 14.5194 10.8142 13.3164 12.3077 13.3164H13.7868V21.6159C13.7868 22.4904 14.5029 23.2008 15.3846 23.2008V11.7279H12.3077ZM19.6923 20.2701C22.0711 20.2701 24 18.3568 24 16.0008C24 13.6448 22.0747 11.7315 19.6923 11.7315H19.0769V13.3164H19.6923C21.1858 13.3164 22.3986 14.5194 22.3986 16.0008C22.3986 17.4822 21.1858 18.6852 19.6923 18.6852H18.2132V10.3857C18.2132 9.51114 17.4971 8.80078 16.6154 8.80078V20.2701H19.6923Z"
         fill="white"
       />
     </svg>
    }
  >
    Quickbooks is a cloud-based accounting software for small businesses.
  </Card>
</CardGroup>

## Taxes integrations

{" "}

<CardGroup cols={2}>
  <Card
    title="Lago EU Taxes"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#19212E" />
       <g clip-path="url(#clip0_4694_621)">
         <path
           opacity="0.6"
           d="M24 15.8647C24 16.0887 23.992 16.3127 23.968 16.5367C23.96 16.7207 23.936 16.9047 23.904 17.0807C23.896 17.1367 23.888 17.1927 23.88 17.2407C23.848 17.4247 23.808 17.6007 23.76 17.7767C23.76 17.7927 23.76 17.8087 23.752 17.8247C23.752 17.8407 23.752 17.8487 23.744 17.8647C23.696 18.0647 23.632 18.2567 23.568 18.4487C23.552 18.4887 23.544 18.5287 23.52 18.5687C23.312 18.9607 22.808 19.1047 22.408 18.8727L17 15.7527C16.752 15.6087 16.6 15.3447 16.6 15.0567V8.80874C16.6 8.30473 17.056 7.92074 17.552 8.01674C17.76 8.05674 17.968 8.10474 18.176 8.16874C18.192 8.17674 18.208 8.17674 18.224 8.18474C18.4 8.23274 18.576 8.28874 18.744 8.35274C18.76 8.35274 18.776 8.36074 18.792 8.36874C18.88 8.40074 18.968 8.44074 19.056 8.48074C19.192 8.52874 19.328 8.59274 19.456 8.65674C19.496 8.67274 19.528 8.68874 19.56 8.70474C19.6 8.72874 19.64 8.74474 19.672 8.76874C19.688 8.77674 19.712 8.78474 19.728 8.79274C19.8 8.82474 19.864 8.86474 19.928 8.90474C19.944 8.91274 19.952 8.92073 19.968 8.92873C20.048 8.96873 20.12 9.01674 20.192 9.06474H20.2C20.36 9.16074 20.512 9.26474 20.664 9.37674C20.704 9.40074 20.744 9.42474 20.776 9.45674C20.896 9.54474 21.016 9.64074 21.136 9.74474C21.152 9.75274 21.16 9.76874 21.176 9.77674C21.48 10.0327 21.76 10.3127 22.024 10.6167C22.104 10.7047 22.176 10.7927 22.256 10.8887C22.384 11.0567 22.512 11.2327 22.632 11.4087C22.704 11.5127 22.768 11.6167 22.832 11.7207C22.92 11.8647 23 12.0087 23.08 12.1607C23.088 12.1847 23.104 12.2007 23.112 12.2247C23.2 12.3927 23.288 12.5687 23.36 12.7527C23.4 12.8487 23.44 12.9367 23.472 13.0327C23.496 13.0887 23.52 13.1447 23.536 13.2007C23.544 13.2247 23.552 13.2407 23.56 13.2647C23.584 13.3367 23.608 13.4167 23.632 13.4887C23.696 13.6887 23.752 13.8887 23.792 14.0967C23.816 14.2007 23.84 14.2967 23.856 14.4007C23.944 14.8727 23.992 15.3607 23.992 15.8647H24Z"
           fill="white"
         />
         <path
           d="M22.016 21.1287C21.928 21.2327 21.84 21.3367 21.736 21.4327C21.64 21.5367 21.536 21.6407 21.432 21.7287C20.856 22.2727 20.192 22.7287 19.464 23.0727C19.352 23.1287 19.232 23.1847 19.112 23.2327C19 23.2807 18.888 23.3287 18.776 23.3687C18.432 23.4967 18.08 23.6007 17.72 23.6807C17.6 23.7047 17.48 23.7287 17.36 23.7447C17.184 23.7767 17 23.8007 16.816 23.8247C16.544 23.8487 16.272 23.8647 16 23.8647C15.88 23.8647 15.768 23.8647 15.656 23.8567C15.536 23.8487 15.424 23.8487 15.304 23.8327C15.24 23.8327 15.184 23.8327 15.128 23.8167C14.888 23.7927 14.648 23.7527 14.416 23.7047C14.4 23.7047 14.384 23.6967 14.368 23.6967C11.264 23.0487 8.816 20.6087 8.168 17.5047C8.168 17.4807 8.16 17.4567 8.152 17.4327C8.112 17.2087 8.072 16.9767 8.048 16.7367C8.04 16.6807 8.032 16.6247 8.032 16.5607C8.016 16.4407 8.016 16.3287 8.008 16.2087C8 16.0967 8 15.9847 8 15.8647C8 15.3607 8.048 14.8727 8.136 14.4007C8.152 14.2967 8.176 14.2007 8.2 14.0967C8.24 13.8887 8.296 13.6887 8.36 13.4887C8.44 13.2327 8.528 12.9927 8.632 12.7527C8.728 12.5127 8.84 12.2807 8.968 12.0487C9.024 11.9367 9.088 11.8247 9.16 11.7207C9.224 11.6167 9.288 11.5127 9.36 11.4087C10.08 10.3367 11.048 9.44873 12.184 8.83273C12.416 8.70473 12.648 8.59274 12.888 8.49674C13.008 8.44074 13.128 8.39274 13.248 8.35274C13.36 8.31274 13.464 8.27274 13.576 8.24074C13.712 8.19274 13.856 8.15274 14 8.12074C14.096 8.08874 14.192 8.07274 14.288 8.04874C14.336 8.04074 14.392 8.02474 14.448 8.01674C14.936 7.92074 15.4 8.30473 15.4 8.80874V15.7447C15.4 16.0327 15.552 16.2967 15.8 16.4407L21.808 19.9047C22.248 20.1607 22.352 20.7527 22.016 21.1287Z"
           fill="white"
         />
       </g>
       <defs>
         <clipPath id="clip0_4694_621">
           <rect
             width="16"
             height="16"
             fill="white"
             transform="translate(8 8)"
           />
         </clipPath>
       </defs>
     </svg>
    }
    href="/integrations/taxes/lago-eu-taxes"
  >
    Lago now features an automatic European tax detection integration for your
    customers.
  </Card>

  <Card
    title="Anrok"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#1D192F" />
       <path
         d="M13.8039 8.80078C15.2157 8.80078 16.6275 8.80078 18.0392 8.80078C18.1333 8.98902 18.2141 9.18401 18.3239 9.364C19.8784 11.9154 21.4329 14.466 22.9953 17.0121C23.3153 17.5333 23.6643 18.0381 24 18.5503V20.2752C23.5224 21.0904 23.0408 21.9041 22.5694 22.7231C22.4643 22.906 22.3396 22.9833 22.1098 22.981C20.9741 22.9683 19.8384 22.969 18.7035 22.981C18.4659 22.9833 18.3263 22.9165 18.2063 22.7171C17.4306 21.4316 16.6424 20.1537 15.8573 18.8735C15.8024 18.7835 15.7388 18.698 15.6792 18.6103C15.6369 18.7183 15.6471 18.8023 15.6596 18.8863C15.8518 20.2174 15.4588 21.3476 14.4133 22.2633C13.7929 22.8063 13.0384 23.0515 12.2353 23.2008H11.451C11.3898 23.1798 11.331 23.1513 11.2682 23.14C9.71686 22.8633 8.69098 22.0061 8.1898 20.5797C8.10353 20.3352 8.06196 20.0772 8 19.8252C8 19.6002 8 19.3752 8 19.1502C8.02353 19.0677 8.05647 18.986 8.0698 18.902C8.36627 16.9821 10.2886 15.5947 12.3043 15.8287C13.1318 15.9247 13.8384 16.2591 14.4965 16.7414C14.4706 16.6266 14.4298 16.5276 14.3741 16.4369C13.6165 15.1979 12.8651 13.9553 12.0925 12.7253C11.9341 12.4733 11.9004 12.2829 12.0635 12.0144C12.4384 11.4001 12.7757 10.7657 13.1176 10.1342C13.3553 9.69398 13.5757 9.24551 13.8039 8.80078Z"
         fill="white"
       />
     </svg>
    }
    href="/integrations/taxes/anrok"
  >
    Anrok is the global sales tax platform for software companies.
  </Card>
</CardGroup>

## CRM integrations

<CardGroup cols={2}>
  <Card
    title="Salesforce CRM"
    iconType="brand"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#00A1E0" />
       <path
         fill-rule="evenodd"
         clip-rule="evenodd"
         d="M14.1208 9.70778C14.8435 8.95546 15.8494 8.48958 16.9606 8.48958C18.4421 8.48958 19.7262 9.31269 20.4176 10.5391C21.0313 10.2648 21.6961 10.1231 22.3684 10.1234C25.0352 10.1234 27.2 12.3047 27.2 14.9962C27.2 17.6878 25.0352 19.869 22.3684 19.869C22.0424 19.869 21.7247 19.8363 21.4136 19.7744C20.8086 20.8526 19.6521 21.5852 18.3351 21.5852C17.799 21.5863 17.2696 21.4646 16.7877 21.2296C16.1745 22.6701 14.7464 23.6825 13.0837 23.6825C11.347 23.6825 9.87361 22.5877 9.30567 21.0485C9.05289 21.1019 8.79523 21.1287 8.53689 21.1285C6.47089 21.1285 4.79999 19.4329 4.79999 17.3505C4.79999 15.9512 5.55231 14.733 6.66844 14.0745C6.43165 13.529 6.30977 12.9406 6.31039 12.346C6.31039 9.94253 8.26115 8 10.6646 8C12.0721 8 13.3315 8.67083 14.1217 9.71206"
         fill="white"
       />
       <path
         fill-rule="evenodd"
         clip-rule="evenodd"
         d="M18.0423 13.4844C18.0856 13.492 18.1285 13.5022 18.1706 13.5149C18.1798 13.5185 18.2047 13.5308 18.1945 13.5602L18.0952 13.8328C18.0869 13.8533 18.0812 13.8658 18.0389 13.8528C18.0284 13.8497 18.0127 13.8452 17.9725 13.8366C17.9432 13.8305 17.9049 13.8258 17.8658 13.8258C17.8186 13.8252 17.7716 13.832 17.7264 13.8459C17.6853 13.8594 17.648 13.8826 17.6177 13.9136C17.5853 13.9461 17.547 13.9934 17.5267 14.0521C17.4852 14.1716 17.4656 14.2976 17.4598 14.3346C17.4589 14.3402 17.4584 14.3438 17.4581 14.345H17.8732C17.9079 14.3448 17.919 14.361 17.9156 14.3868L17.8672 14.6568C17.8597 14.6959 17.8237 14.6946 17.8237 14.6946H17.396L17.1034 16.3497C17.0727 16.5209 17.0344 16.6677 16.9894 16.786C16.9438 16.9053 16.8963 16.9928 16.8206 17.0764C16.7507 17.1538 16.6716 17.211 16.5807 17.2439C16.4904 17.2765 16.3815 17.2933 16.262 17.2933C16.2049 17.2933 16.144 17.2922 16.0718 17.2752C16.0197 17.2629 15.9913 17.2542 15.9531 17.2405C15.9368 17.2347 15.9239 17.2144 15.9331 17.1887C15.9422 17.1627 16.0187 16.9524 16.0294 16.9248C16.0427 16.8911 16.0764 16.9039 16.0764 16.9039L16.078 16.9046C16.1003 16.914 16.1163 16.9207 16.1464 16.9267C16.1773 16.9328 16.2191 16.9381 16.2505 16.9381C16.307 16.9381 16.3585 16.9312 16.4033 16.9161C16.4575 16.8979 16.489 16.8667 16.5222 16.8243C16.5564 16.7806 16.5842 16.7202 16.6127 16.6397C16.6416 16.5582 16.6677 16.4505 16.6905 16.3196L16.9816 14.6946H16.6947C16.6601 14.6947 16.649 14.6786 16.6524 14.6527L16.7008 14.3828C16.7083 14.3435 16.7443 14.345 16.7443 14.345H17.0391L17.055 14.257C17.099 13.9963 17.1868 13.7982 17.3159 13.6681C17.4458 13.5371 17.631 13.4708 17.8658 13.4708C17.9249 13.4701 17.984 13.4747 18.0423 13.4844ZM12.3326 16.3625C12.3544 16.3625 12.3698 16.3448 12.3698 16.3231V13.5518C12.3698 13.5302 12.3544 13.5127 12.3326 13.5127H11.9883C11.9665 13.5127 11.951 13.5302 11.951 13.5518V16.3231C11.951 16.3448 11.9665 16.3625 11.9883 16.3625H12.3326ZM8.0689 16.1757C8.06217 16.1693 8.05113 16.1588 8.06277 16.1284L8.06244 16.1278L8.15298 15.8759C8.1673 15.8328 8.20023 15.8472 8.2134 15.8551C8.22351 15.8613 8.23254 15.8672 8.24188 15.8733C8.25557 15.8822 8.26989 15.8916 8.28912 15.9028C8.55663 16.0719 8.80348 16.0732 8.88094 16.0732C9.08013 16.0732 9.20442 15.967 9.20442 15.8246V15.8169C9.20442 15.6621 9.01346 15.6032 8.79286 15.5354L8.74414 15.5202C8.44123 15.4338 8.11693 15.3087 8.11693 14.9251V14.9173C8.11693 14.5535 8.41078 14.2991 8.83139 14.2991L8.87723 14.299C9.12416 14.299 9.36286 14.3706 9.53572 14.4759C9.55144 14.4853 9.56675 14.5035 9.55802 14.5276C9.54979 14.5507 9.473 14.7562 9.46419 14.7795C9.44797 14.8226 9.40336 14.7937 9.40336 14.7937C9.25273 14.7105 9.01732 14.6448 8.81978 14.6448C8.64199 14.6448 8.52675 14.7394 8.52675 14.8678V14.8755C8.52675 15.0253 8.72348 15.0897 8.95148 15.1636L8.9909 15.1763C9.29216 15.271 9.61482 15.4035 9.61482 15.7673V15.7751C9.61482 16.1685 9.3292 16.413 8.86991 16.413C8.64438 16.413 8.42872 16.3776 8.1999 16.2566C8.18991 16.2508 8.17992 16.2452 8.16995 16.2395C8.13719 16.221 8.10456 16.2026 8.07232 16.1793C8.07153 16.1782 8.07031 16.177 8.0689 16.1757ZM14.7935 16.1751C14.7867 16.1687 14.7755 16.1582 14.7872 16.1278L14.7862 16.1271L14.8768 15.8752C14.89 15.8341 14.9288 15.8492 14.9371 15.8545C14.9427 15.8581 14.9479 15.8615 14.9531 15.8649C14.9709 15.8765 14.9879 15.8876 15.0129 15.9021C15.2796 16.0712 15.5271 16.0725 15.6047 16.0725C15.8039 16.0725 15.9282 15.9663 15.9282 15.8239V15.8162C15.9282 15.6615 15.7381 15.6025 15.5167 15.5347L15.468 15.5196C15.1651 15.4331 14.8408 15.308 14.8408 14.9245V14.9166C14.8408 14.5528 15.1346 14.2985 15.5553 14.2985L15.6012 14.2983C15.8481 14.2983 16.0868 14.3699 16.2597 14.4753C16.2753 14.4847 16.2907 14.5029 16.2819 14.527C16.2745 14.55 16.1976 14.7556 16.1889 14.7789C16.1726 14.8219 16.128 14.7931 16.128 14.7931C15.9765 14.7099 15.7419 14.6441 15.5444 14.6441C15.3666 14.6441 15.2514 14.7388 15.2514 14.8672V14.8748C15.2514 15.0246 15.4481 15.089 15.6761 15.1629L15.7155 15.1757C16.0176 15.2703 16.3394 15.4028 16.3394 15.7667V15.7744C16.3394 16.1678 16.0538 16.4123 15.5945 16.4123C15.369 16.4123 15.1533 16.3769 14.9245 16.2559C14.9144 16.2501 14.9043 16.2444 14.8942 16.2387C14.8615 16.2203 14.8289 16.2019 14.7969 16.1786C14.7961 16.1775 14.7949 16.1764 14.7935 16.1751ZM19.2565 15.8785C19.3377 15.7542 19.3792 15.5789 19.3792 15.3567V15.3575C19.3792 15.1353 19.3382 14.9608 19.2565 14.8381C19.1759 14.7169 19.054 14.6579 18.8828 14.6579C18.7116 14.6579 18.5905 14.7163 18.5108 14.8381C18.4306 14.9608 18.3898 15.1353 18.3898 15.3575C18.3898 15.5797 18.4304 15.7559 18.5108 15.8793C18.5906 16.0017 18.7124 16.0612 18.8828 16.0612C19.0532 16.0612 19.1755 16.0012 19.2565 15.8785ZM19.5882 14.6118C19.6664 14.7056 19.7249 14.8175 19.7627 14.9451H19.7619C19.7993 15.0719 19.8183 15.211 19.8183 15.3575C19.8183 15.5048 19.7993 15.6431 19.7619 15.7699C19.724 15.8975 19.6655 16.0094 19.5874 16.1032C19.5092 16.1971 19.4096 16.2721 19.2927 16.3255C19.1759 16.3788 19.0376 16.406 18.882 16.406C18.7264 16.406 18.5882 16.3788 18.4704 16.3255C18.3536 16.272 18.2541 16.1971 18.1758 16.1032C18.0976 16.0094 18.0389 15.8975 18.0013 15.7699C17.9638 15.6431 17.9448 15.5048 17.9448 15.3575C17.9448 15.2102 17.9638 15.0719 18.0013 14.9451C18.0391 14.8175 18.0977 14.7056 18.1758 14.6118C18.254 14.5179 18.3536 14.4425 18.4704 14.3879C18.5882 14.3333 18.7256 14.3056 18.882 14.3056C19.0384 14.3056 19.1767 14.3331 19.2936 14.3879C19.4113 14.4422 19.5099 14.5179 19.5882 14.6118ZM22.8654 15.9755C22.8654 15.9755 22.9018 15.9614 22.9144 15.9987H22.9147L23.0094 16.2588C23.0214 16.2911 22.9937 16.3044 22.9937 16.3044C22.8489 16.3618 22.6472 16.4015 22.4505 16.4015C22.118 16.4015 21.8628 16.306 21.6932 16.1167C21.5237 15.9282 21.4381 15.6706 21.4381 15.3529C21.4381 15.2055 21.4591 15.0664 21.5006 14.9397C21.5426 14.8121 21.6052 14.7002 21.6875 14.6063C21.7698 14.5125 21.8735 14.437 21.9961 14.3824C22.1188 14.3278 22.262 14.3002 22.4233 14.3002C22.532 14.3002 22.6283 14.3068 22.7114 14.3195C22.8003 14.3329 22.9177 14.3647 22.9674 14.3842C22.9765 14.3877 23.0016 14.4001 22.9914 14.4293C22.9671 14.4978 22.9479 14.5503 22.9278 14.6056C22.9179 14.6327 22.9078 14.6604 22.8967 14.691C22.8823 14.7306 22.8523 14.7175 22.8523 14.7175C22.7255 14.6779 22.6045 14.6595 22.4465 14.6595C22.2571 14.6595 22.1139 14.7237 22.0209 14.8472C21.9267 14.9723 21.8742 15.1353 21.8736 15.3526C21.8728 15.5913 21.932 15.7674 22.0382 15.8769C22.1436 15.9863 22.2917 16.0415 22.4769 16.0415C22.5518 16.0415 22.6229 16.0365 22.6868 16.0264C22.7502 16.0166 22.8097 15.9968 22.8654 15.9755ZM23.5856 15.1425C23.5856 15.1426 23.5856 15.1426 23.5856 15.1427L23.5814 15.1425L23.5856 15.1425ZM23.5856 15.1425L24.5116 15.1427C24.5028 15.0233 24.4795 14.9167 24.426 14.8365C24.3453 14.715 24.2325 14.648 24.0621 14.648C23.8918 14.648 23.7705 14.7146 23.6909 14.8365C23.6378 14.9163 23.6039 15.0191 23.5856 15.1425ZM24.7116 14.5673C24.7642 14.6241 24.8452 14.7484 24.8778 14.871L24.8796 14.8713C24.9578 15.1457 24.9245 15.3854 24.919 15.425C24.9187 15.4276 24.9184 15.4293 24.9183 15.4302C24.9148 15.4636 24.8806 15.4639 24.8806 15.4639L23.58 15.4629C23.5875 15.6605 23.6352 15.7996 23.7307 15.8951C23.8245 15.9883 23.9735 16.0478 24.1752 16.0482C24.4565 16.0489 24.5909 15.9971 24.6829 15.9617C24.6918 15.9582 24.7003 15.9549 24.7085 15.9519C24.7085 15.9519 24.7444 15.939 24.7574 15.9745L24.8422 16.2124C24.8592 16.2525 24.8456 16.2664 24.8312 16.2744C24.7505 16.3197 24.553 16.4033 24.1776 16.4045C23.9957 16.4051 23.8369 16.3788 23.706 16.3282C23.5743 16.2772 23.4648 16.2047 23.3792 16.1117C23.2936 16.0195 23.2301 15.9084 23.1907 15.7816C23.1517 15.6557 23.1319 15.5166 23.1319 15.3668C23.1319 15.2203 23.151 15.0804 23.1888 14.9528C23.2267 14.8235 23.286 14.7108 23.365 14.6153C23.444 14.5198 23.5444 14.4434 23.6638 14.3873C23.7831 14.3316 23.9304 14.3042 24.0926 14.3042C24.2204 14.3039 24.347 14.3296 24.4646 14.3796C24.5461 14.4142 24.6276 14.4776 24.7116 14.5673ZM13.1898 15.1425C13.1897 15.1426 13.1897 15.1426 13.1897 15.1427L13.1856 15.1425L13.1898 15.1425ZM13.2951 14.8365C13.242 14.9163 13.2081 15.0191 13.1898 15.1425L14.1157 15.1427C14.1069 15.0233 14.0835 14.9167 14.0301 14.8365C13.9495 14.715 13.8367 14.648 13.6663 14.648C13.4959 14.648 13.3748 14.7146 13.2951 14.8365ZM14.3157 14.5673C14.3684 14.6241 14.4494 14.7484 14.482 14.871L14.4829 14.8713C14.5612 15.1457 14.5279 15.3854 14.5224 15.425C14.5221 15.4276 14.5218 15.4293 14.5218 15.4302C14.5182 15.4636 14.484 15.4639 14.484 15.4639L13.1835 15.4629C13.1909 15.6605 13.2386 15.7996 13.3341 15.8951C13.4279 15.9883 13.5777 16.0478 13.7786 16.0482C14.06 16.0489 14.1943 15.9971 14.2863 15.9617C14.2952 15.9582 14.3037 15.9549 14.312 15.9519C14.312 15.9519 14.3478 15.939 14.3609 15.9745L14.4457 16.2124C14.4627 16.2525 14.4491 16.2664 14.4348 16.2744C14.3541 16.3197 14.1566 16.4033 13.7812 16.4045C13.5985 16.4051 13.4404 16.3788 13.3096 16.3282C13.1779 16.2772 13.0684 16.2047 12.9828 16.1117C12.898 16.0195 12.8345 15.9084 12.7951 15.7816C12.7559 15.6557 12.7362 15.5166 12.7362 15.3668C12.7362 15.2203 12.7552 15.0804 12.793 14.9528C12.8309 14.8235 12.8904 14.7108 12.9691 14.6153C13.0482 14.5198 13.1486 14.4434 13.2679 14.3873C13.3873 14.3316 13.5346 14.3042 13.6968 14.3042C13.8246 14.3039 13.9512 14.3296 14.0688 14.3796C14.1503 14.4142 14.2318 14.4776 14.3157 14.5673ZM10.308 15.9134C10.3249 15.9398 10.332 15.9498 10.3829 15.9905L10.3837 15.9909C10.3829 15.9906 10.4997 16.0826 10.764 16.0667C10.95 16.0555 11.1146 16.02 11.1146 16.02H11.1144V15.4298C10.9978 15.412 10.8801 15.4019 10.7621 15.3998C10.4971 15.3965 10.3843 15.4938 10.3852 15.4936C10.307 15.5488 10.2691 15.6311 10.2691 15.7447C10.2691 15.8171 10.2823 15.8737 10.308 15.9134ZM10.6974 15.0711C10.7789 15.0711 10.8472 15.0729 10.8999 15.0768L10.9011 15.0799C10.9011 15.0799 11.004 15.0892 11.1151 15.1053V15.0504C11.1151 14.8775 11.079 14.7953 11.0081 14.7409C10.9357 14.6853 10.827 14.6569 10.6871 14.6569C10.6871 14.6569 10.371 14.6528 10.1216 14.7886C10.1101 14.7955 10.1003 14.7993 10.1003 14.7993C10.1003 14.7993 10.0691 14.8103 10.0576 14.7783L9.96546 14.5313C9.95147 14.4955 9.97715 14.4797 9.97715 14.4797C10.094 14.3882 10.3772 14.3332 10.3772 14.3332C10.471 14.3144 10.6282 14.3012 10.7254 14.3012C10.9846 14.3012 11.1846 14.3613 11.3213 14.4806C11.4584 14.6 11.5279 14.7934 11.5279 15.0535L11.5286 16.2388C11.5286 16.2388 11.5311 16.2731 11.499 16.2813C11.499 16.2813 11.4509 16.2944 11.4076 16.3043C11.2992 16.3278 11.1902 16.349 11.0809 16.3679C10.9524 16.3895 10.8199 16.4007 10.6866 16.4007C10.5598 16.4007 10.4446 16.3889 10.3425 16.3656C10.2396 16.3426 10.1505 16.3037 10.0783 16.2512C10.0057 16.1986 9.94746 16.1287 9.90875 16.0479C9.86924 15.9664 9.84924 15.8668 9.84924 15.7516C9.84924 15.638 9.8727 15.5376 9.91871 15.452C9.9643 15.3671 10.0288 15.2939 10.1072 15.238C10.1854 15.1817 10.2768 15.1394 10.378 15.112C10.4784 15.0849 10.5862 15.0711 10.6974 15.0711ZM21.3562 14.3939C21.3561 14.3986 21.3552 14.4033 21.3533 14.4076L21.3541 14.4023C21.3418 14.4377 21.2785 14.6154 21.2562 14.6747C21.2477 14.6973 21.2338 14.7126 21.2088 14.7098C21.2088 14.7098 21.1343 14.6923 21.0664 14.6923C21.0073 14.6923 20.9486 14.7006 20.8919 14.7169C20.8314 14.7356 20.7764 14.7687 20.7314 14.8132C20.6842 14.8593 20.6459 14.9236 20.6178 15.0041C20.5892 15.0856 20.5749 15.2148 20.5749 15.3449V16.3162C20.5749 16.3266 20.5707 16.3366 20.5634 16.344C20.556 16.3514 20.546 16.3556 20.5355 16.3556H20.1948C20.1843 16.3556 20.1743 16.3514 20.1669 16.344C20.1595 16.3366 20.1554 16.3266 20.1553 16.3162V14.3819C20.1553 14.3601 20.171 14.3426 20.1926 14.3426H20.5251C20.547 14.3426 20.5624 14.3601 20.5624 14.3819L20.5625 14.5399C20.6119 14.4724 20.701 14.4141 20.7815 14.3778C20.863 14.3412 20.9535 14.3137 21.1165 14.3239C21.2013 14.3292 21.3116 14.3525 21.3338 14.3609C21.3382 14.3626 21.3422 14.3652 21.3456 14.3685C21.349 14.3718 21.3516 14.3758 21.3535 14.3801C21.3553 14.3845 21.3562 14.3892 21.3562 14.3939Z"
         fill="#00A1E0"
       />
     </svg>
    }
    href="/integrations/crm/salesforce-crm"
  >
    Salesforce CRM integration is used to sync data from Lago to Salesforce.
  </Card>

  <Card
    title="Salesforce CPQ"
    iconType="brand"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#00A1E0" />
       <path
         fill-rule="evenodd"
         clip-rule="evenodd"
         d="M14.1208 9.70778C14.8435 8.95546 15.8494 8.48958 16.9606 8.48958C18.4421 8.48958 19.7262 9.31269 20.4176 10.5391C21.0313 10.2648 21.6961 10.1231 22.3684 10.1234C25.0352 10.1234 27.2 12.3047 27.2 14.9962C27.2 17.6878 25.0352 19.869 22.3684 19.869C22.0424 19.869 21.7247 19.8363 21.4136 19.7744C20.8086 20.8526 19.6521 21.5852 18.3351 21.5852C17.799 21.5863 17.2696 21.4646 16.7877 21.2296C16.1745 22.6701 14.7464 23.6825 13.0837 23.6825C11.347 23.6825 9.87361 22.5877 9.30567 21.0485C9.05289 21.1019 8.79523 21.1287 8.53689 21.1285C6.47089 21.1285 4.79999 19.4329 4.79999 17.3505C4.79999 15.9512 5.55231 14.733 6.66844 14.0745C6.43165 13.529 6.30977 12.9406 6.31039 12.346C6.31039 9.94253 8.26115 8 10.6646 8C12.0721 8 13.3315 8.67083 14.1217 9.71206"
         fill="white"
       />
       <path
         fill-rule="evenodd"
         clip-rule="evenodd"
         d="M18.0423 13.4844C18.0856 13.492 18.1285 13.5022 18.1706 13.5149C18.1798 13.5185 18.2047 13.5308 18.1945 13.5602L18.0952 13.8328C18.0869 13.8533 18.0812 13.8658 18.0389 13.8528C18.0284 13.8497 18.0127 13.8452 17.9725 13.8366C17.9432 13.8305 17.9049 13.8258 17.8658 13.8258C17.8186 13.8252 17.7716 13.832 17.7264 13.8459C17.6853 13.8594 17.648 13.8826 17.6177 13.9136C17.5853 13.9461 17.547 13.9934 17.5267 14.0521C17.4852 14.1716 17.4656 14.2976 17.4598 14.3346C17.4589 14.3402 17.4584 14.3438 17.4581 14.345H17.8732C17.9079 14.3448 17.919 14.361 17.9156 14.3868L17.8672 14.6568C17.8597 14.6959 17.8237 14.6946 17.8237 14.6946H17.396L17.1034 16.3497C17.0727 16.5209 17.0344 16.6677 16.9894 16.786C16.9438 16.9053 16.8963 16.9928 16.8206 17.0764C16.7507 17.1538 16.6716 17.211 16.5807 17.2439C16.4904 17.2765 16.3815 17.2933 16.262 17.2933C16.2049 17.2933 16.144 17.2922 16.0718 17.2752C16.0197 17.2629 15.9913 17.2542 15.9531 17.2405C15.9368 17.2347 15.9239 17.2144 15.9331 17.1887C15.9422 17.1627 16.0187 16.9524 16.0294 16.9248C16.0427 16.8911 16.0764 16.9039 16.0764 16.9039L16.078 16.9046C16.1003 16.914 16.1163 16.9207 16.1464 16.9267C16.1773 16.9328 16.2191 16.9381 16.2505 16.9381C16.307 16.9381 16.3585 16.9312 16.4033 16.9161C16.4575 16.8979 16.489 16.8667 16.5222 16.8243C16.5564 16.7806 16.5842 16.7202 16.6127 16.6397C16.6416 16.5582 16.6677 16.4505 16.6905 16.3196L16.9816 14.6946H16.6947C16.6601 14.6947 16.649 14.6786 16.6524 14.6527L16.7008 14.3828C16.7083 14.3435 16.7443 14.345 16.7443 14.345H17.0391L17.055 14.257C17.099 13.9963 17.1868 13.7982 17.3159 13.6681C17.4458 13.5371 17.631 13.4708 17.8658 13.4708C17.9249 13.4701 17.984 13.4747 18.0423 13.4844ZM12.3326 16.3625C12.3544 16.3625 12.3698 16.3448 12.3698 16.3231V13.5518C12.3698 13.5302 12.3544 13.5127 12.3326 13.5127H11.9883C11.9665 13.5127 11.951 13.5302 11.951 13.5518V16.3231C11.951 16.3448 11.9665 16.3625 11.9883 16.3625H12.3326ZM8.0689 16.1757C8.06217 16.1693 8.05113 16.1588 8.06277 16.1284L8.06244 16.1278L8.15298 15.8759C8.1673 15.8328 8.20023 15.8472 8.2134 15.8551C8.22351 15.8613 8.23254 15.8672 8.24188 15.8733C8.25557 15.8822 8.26989 15.8916 8.28912 15.9028C8.55663 16.0719 8.80348 16.0732 8.88094 16.0732C9.08013 16.0732 9.20442 15.967 9.20442 15.8246V15.8169C9.20442 15.6621 9.01346 15.6032 8.79286 15.5354L8.74414 15.5202C8.44123 15.4338 8.11693 15.3087 8.11693 14.9251V14.9173C8.11693 14.5535 8.41078 14.2991 8.83139 14.2991L8.87723 14.299C9.12416 14.299 9.36286 14.3706 9.53572 14.4759C9.55144 14.4853 9.56675 14.5035 9.55802 14.5276C9.54979 14.5507 9.473 14.7562 9.46419 14.7795C9.44797 14.8226 9.40336 14.7937 9.40336 14.7937C9.25273 14.7105 9.01732 14.6448 8.81978 14.6448C8.64199 14.6448 8.52675 14.7394 8.52675 14.8678V14.8755C8.52675 15.0253 8.72348 15.0897 8.95148 15.1636L8.9909 15.1763C9.29216 15.271 9.61482 15.4035 9.61482 15.7673V15.7751C9.61482 16.1685 9.3292 16.413 8.86991 16.413C8.64438 16.413 8.42872 16.3776 8.1999 16.2566C8.18991 16.2508 8.17992 16.2452 8.16995 16.2395C8.13719 16.221 8.10456 16.2026 8.07232 16.1793C8.07153 16.1782 8.07031 16.177 8.0689 16.1757ZM14.7935 16.1751C14.7867 16.1687 14.7755 16.1582 14.7872 16.1278L14.7862 16.1271L14.8768 15.8752C14.89 15.8341 14.9288 15.8492 14.9371 15.8545C14.9427 15.8581 14.9479 15.8615 14.9531 15.8649C14.9709 15.8765 14.9879 15.8876 15.0129 15.9021C15.2796 16.0712 15.5271 16.0725 15.6047 16.0725C15.8039 16.0725 15.9282 15.9663 15.9282 15.8239V15.8162C15.9282 15.6615 15.7381 15.6025 15.5167 15.5347L15.468 15.5196C15.1651 15.4331 14.8408 15.308 14.8408 14.9245V14.9166C14.8408 14.5528 15.1346 14.2985 15.5553 14.2985L15.6012 14.2983C15.8481 14.2983 16.0868 14.3699 16.2597 14.4753C16.2753 14.4847 16.2907 14.5029 16.2819 14.527C16.2745 14.55 16.1976 14.7556 16.1889 14.7789C16.1726 14.8219 16.128 14.7931 16.128 14.7931C15.9765 14.7099 15.7419 14.6441 15.5444 14.6441C15.3666 14.6441 15.2514 14.7388 15.2514 14.8672V14.8748C15.2514 15.0246 15.4481 15.089 15.6761 15.1629L15.7155 15.1757C16.0176 15.2703 16.3394 15.4028 16.3394 15.7667V15.7744C16.3394 16.1678 16.0538 16.4123 15.5945 16.4123C15.369 16.4123 15.1533 16.3769 14.9245 16.2559C14.9144 16.2501 14.9043 16.2444 14.8942 16.2387C14.8615 16.2203 14.8289 16.2019 14.7969 16.1786C14.7961 16.1775 14.7949 16.1764 14.7935 16.1751ZM19.2565 15.8785C19.3377 15.7542 19.3792 15.5789 19.3792 15.3567V15.3575C19.3792 15.1353 19.3382 14.9608 19.2565 14.8381C19.1759 14.7169 19.054 14.6579 18.8828 14.6579C18.7116 14.6579 18.5905 14.7163 18.5108 14.8381C18.4306 14.9608 18.3898 15.1353 18.3898 15.3575C18.3898 15.5797 18.4304 15.7559 18.5108 15.8793C18.5906 16.0017 18.7124 16.0612 18.8828 16.0612C19.0532 16.0612 19.1755 16.0012 19.2565 15.8785ZM19.5882 14.6118C19.6664 14.7056 19.7249 14.8175 19.7627 14.9451H19.7619C19.7993 15.0719 19.8183 15.211 19.8183 15.3575C19.8183 15.5048 19.7993 15.6431 19.7619 15.7699C19.724 15.8975 19.6655 16.0094 19.5874 16.1032C19.5092 16.1971 19.4096 16.2721 19.2927 16.3255C19.1759 16.3788 19.0376 16.406 18.882 16.406C18.7264 16.406 18.5882 16.3788 18.4704 16.3255C18.3536 16.272 18.2541 16.1971 18.1758 16.1032C18.0976 16.0094 18.0389 15.8975 18.0013 15.7699C17.9638 15.6431 17.9448 15.5048 17.9448 15.3575C17.9448 15.2102 17.9638 15.0719 18.0013 14.9451C18.0391 14.8175 18.0977 14.7056 18.1758 14.6118C18.254 14.5179 18.3536 14.4425 18.4704 14.3879C18.5882 14.3333 18.7256 14.3056 18.882 14.3056C19.0384 14.3056 19.1767 14.3331 19.2936 14.3879C19.4113 14.4422 19.5099 14.5179 19.5882 14.6118ZM22.8654 15.9755C22.8654 15.9755 22.9018 15.9614 22.9144 15.9987H22.9147L23.0094 16.2588C23.0214 16.2911 22.9937 16.3044 22.9937 16.3044C22.8489 16.3618 22.6472 16.4015 22.4505 16.4015C22.118 16.4015 21.8628 16.306 21.6932 16.1167C21.5237 15.9282 21.4381 15.6706 21.4381 15.3529C21.4381 15.2055 21.4591 15.0664 21.5006 14.9397C21.5426 14.8121 21.6052 14.7002 21.6875 14.6063C21.7698 14.5125 21.8735 14.437 21.9961 14.3824C22.1188 14.3278 22.262 14.3002 22.4233 14.3002C22.532 14.3002 22.6283 14.3068 22.7114 14.3195C22.8003 14.3329 22.9177 14.3647 22.9674 14.3842C22.9765 14.3877 23.0016 14.4001 22.9914 14.4293C22.9671 14.4978 22.9479 14.5503 22.9278 14.6056C22.9179 14.6327 22.9078 14.6604 22.8967 14.691C22.8823 14.7306 22.8523 14.7175 22.8523 14.7175C22.7255 14.6779 22.6045 14.6595 22.4465 14.6595C22.2571 14.6595 22.1139 14.7237 22.0209 14.8472C21.9267 14.9723 21.8742 15.1353 21.8736 15.3526C21.8728 15.5913 21.932 15.7674 22.0382 15.8769C22.1436 15.9863 22.2917 16.0415 22.4769 16.0415C22.5518 16.0415 22.6229 16.0365 22.6868 16.0264C22.7502 16.0166 22.8097 15.9968 22.8654 15.9755ZM23.5856 15.1425C23.5856 15.1426 23.5856 15.1426 23.5856 15.1427L23.5814 15.1425L23.5856 15.1425ZM23.5856 15.1425L24.5116 15.1427C24.5028 15.0233 24.4795 14.9167 24.426 14.8365C24.3453 14.715 24.2325 14.648 24.0621 14.648C23.8918 14.648 23.7705 14.7146 23.6909 14.8365C23.6378 14.9163 23.6039 15.0191 23.5856 15.1425ZM24.7116 14.5673C24.7642 14.6241 24.8452 14.7484 24.8778 14.871L24.8796 14.8713C24.9578 15.1457 24.9245 15.3854 24.919 15.425C24.9187 15.4276 24.9184 15.4293 24.9183 15.4302C24.9148 15.4636 24.8806 15.4639 24.8806 15.4639L23.58 15.4629C23.5875 15.6605 23.6352 15.7996 23.7307 15.8951C23.8245 15.9883 23.9735 16.0478 24.1752 16.0482C24.4565 16.0489 24.5909 15.9971 24.6829 15.9617C24.6918 15.9582 24.7003 15.9549 24.7085 15.9519C24.7085 15.9519 24.7444 15.939 24.7574 15.9745L24.8422 16.2124C24.8592 16.2525 24.8456 16.2664 24.8312 16.2744C24.7505 16.3197 24.553 16.4033 24.1776 16.4045C23.9957 16.4051 23.8369 16.3788 23.706 16.3282C23.5743 16.2772 23.4648 16.2047 23.3792 16.1117C23.2936 16.0195 23.2301 15.9084 23.1907 15.7816C23.1517 15.6557 23.1319 15.5166 23.1319 15.3668C23.1319 15.2203 23.151 15.0804 23.1888 14.9528C23.2267 14.8235 23.286 14.7108 23.365 14.6153C23.444 14.5198 23.5444 14.4434 23.6638 14.3873C23.7831 14.3316 23.9304 14.3042 24.0926 14.3042C24.2204 14.3039 24.347 14.3296 24.4646 14.3796C24.5461 14.4142 24.6276 14.4776 24.7116 14.5673ZM13.1898 15.1425C13.1897 15.1426 13.1897 15.1426 13.1897 15.1427L13.1856 15.1425L13.1898 15.1425ZM13.2951 14.8365C13.242 14.9163 13.2081 15.0191 13.1898 15.1425L14.1157 15.1427C14.1069 15.0233 14.0835 14.9167 14.0301 14.8365C13.9495 14.715 13.8367 14.648 13.6663 14.648C13.4959 14.648 13.3748 14.7146 13.2951 14.8365ZM14.3157 14.5673C14.3684 14.6241 14.4494 14.7484 14.482 14.871L14.4829 14.8713C14.5612 15.1457 14.5279 15.3854 14.5224 15.425C14.5221 15.4276 14.5218 15.4293 14.5218 15.4302C14.5182 15.4636 14.484 15.4639 14.484 15.4639L13.1835 15.4629C13.1909 15.6605 13.2386 15.7996 13.3341 15.8951C13.4279 15.9883 13.5777 16.0478 13.7786 16.0482C14.06 16.0489 14.1943 15.9971 14.2863 15.9617C14.2952 15.9582 14.3037 15.9549 14.312 15.9519C14.312 15.9519 14.3478 15.939 14.3609 15.9745L14.4457 16.2124C14.4627 16.2525 14.4491 16.2664 14.4348 16.2744C14.3541 16.3197 14.1566 16.4033 13.7812 16.4045C13.5985 16.4051 13.4404 16.3788 13.3096 16.3282C13.1779 16.2772 13.0684 16.2047 12.9828 16.1117C12.898 16.0195 12.8345 15.9084 12.7951 15.7816C12.7559 15.6557 12.7362 15.5166 12.7362 15.3668C12.7362 15.2203 12.7552 15.0804 12.793 14.9528C12.8309 14.8235 12.8904 14.7108 12.9691 14.6153C13.0482 14.5198 13.1486 14.4434 13.2679 14.3873C13.3873 14.3316 13.5346 14.3042 13.6968 14.3042C13.8246 14.3039 13.9512 14.3296 14.0688 14.3796C14.1503 14.4142 14.2318 14.4776 14.3157 14.5673ZM10.308 15.9134C10.3249 15.9398 10.332 15.9498 10.3829 15.9905L10.3837 15.9909C10.3829 15.9906 10.4997 16.0826 10.764 16.0667C10.95 16.0555 11.1146 16.02 11.1146 16.02H11.1144V15.4298C10.9978 15.412 10.8801 15.4019 10.7621 15.3998C10.4971 15.3965 10.3843 15.4938 10.3852 15.4936C10.307 15.5488 10.2691 15.6311 10.2691 15.7447C10.2691 15.8171 10.2823 15.8737 10.308 15.9134ZM10.6974 15.0711C10.7789 15.0711 10.8472 15.0729 10.8999 15.0768L10.9011 15.0799C10.9011 15.0799 11.004 15.0892 11.1151 15.1053V15.0504C11.1151 14.8775 11.079 14.7953 11.0081 14.7409C10.9357 14.6853 10.827 14.6569 10.6871 14.6569C10.6871 14.6569 10.371 14.6528 10.1216 14.7886C10.1101 14.7955 10.1003 14.7993 10.1003 14.7993C10.1003 14.7993 10.0691 14.8103 10.0576 14.7783L9.96546 14.5313C9.95147 14.4955 9.97715 14.4797 9.97715 14.4797C10.094 14.3882 10.3772 14.3332 10.3772 14.3332C10.471 14.3144 10.6282 14.3012 10.7254 14.3012C10.9846 14.3012 11.1846 14.3613 11.3213 14.4806C11.4584 14.6 11.5279 14.7934 11.5279 15.0535L11.5286 16.2388C11.5286 16.2388 11.5311 16.2731 11.499 16.2813C11.499 16.2813 11.4509 16.2944 11.4076 16.3043C11.2992 16.3278 11.1902 16.349 11.0809 16.3679C10.9524 16.3895 10.8199 16.4007 10.6866 16.4007C10.5598 16.4007 10.4446 16.3889 10.3425 16.3656C10.2396 16.3426 10.1505 16.3037 10.0783 16.2512C10.0057 16.1986 9.94746 16.1287 9.90875 16.0479C9.86924 15.9664 9.84924 15.8668 9.84924 15.7516C9.84924 15.638 9.8727 15.5376 9.91871 15.452C9.9643 15.3671 10.0288 15.2939 10.1072 15.238C10.1854 15.1817 10.2768 15.1394 10.378 15.112C10.4784 15.0849 10.5862 15.0711 10.6974 15.0711ZM21.3562 14.3939C21.3561 14.3986 21.3552 14.4033 21.3533 14.4076L21.3541 14.4023C21.3418 14.4377 21.2785 14.6154 21.2562 14.6747C21.2477 14.6973 21.2338 14.7126 21.2088 14.7098C21.2088 14.7098 21.1343 14.6923 21.0664 14.6923C21.0073 14.6923 20.9486 14.7006 20.8919 14.7169C20.8314 14.7356 20.7764 14.7687 20.7314 14.8132C20.6842 14.8593 20.6459 14.9236 20.6178 15.0041C20.5892 15.0856 20.5749 15.2148 20.5749 15.3449V16.3162C20.5749 16.3266 20.5707 16.3366 20.5634 16.344C20.556 16.3514 20.546 16.3556 20.5355 16.3556H20.1948C20.1843 16.3556 20.1743 16.3514 20.1669 16.344C20.1595 16.3366 20.1554 16.3266 20.1553 16.3162V14.3819C20.1553 14.3601 20.171 14.3426 20.1926 14.3426H20.5251C20.547 14.3426 20.5624 14.3601 20.5624 14.3819L20.5625 14.5399C20.6119 14.4724 20.701 14.4141 20.7815 14.3778C20.863 14.3412 20.9535 14.3137 21.1165 14.3239C21.2013 14.3292 21.3116 14.3525 21.3338 14.3609C21.3382 14.3626 21.3422 14.3652 21.3456 14.3685C21.349 14.3718 21.3516 14.3758 21.3535 14.3801C21.3553 14.3845 21.3562 14.3892 21.3562 14.3939Z"
         fill="#00A1E0"
       />
     </svg>
    }
    href="/integrations/crm/salesforce-cpq"
  >
    Salesforce CPQ extension for Lago's native Salesforce package.
  </Card>

  <Card
    title="HubSpot"
    iconType="brand"
    icon={
     <svg width="30" height="30" viewBox="0 0 40 40" fill="none" xmlns="http://www.w3.org/2000/svg">
    <rect width="40" height="40" rx="12" fill="#FF7A59"/>
    <path d="M26.0258 15.9023V13.0444C26.3965 12.8679 26.7103 12.5877 26.9308 12.2365C27.1513 11.8853 27.2694 11.4776 27.2712 11.0607V10.9951C27.2712 9.77961 26.3041 8.79425 25.1112 8.79425H25.0468C23.8538 8.79425 22.8867 9.77961 22.8867 10.9951V11.0607C22.8886 11.4776 23.0066 11.8853 23.2271 12.2365C23.4476 12.5877 23.7615 12.8679 24.1321 13.0444V15.9023C23.0668 16.0686 22.0634 16.5187 21.2237 17.207L13.5307 11.1019C13.5856 10.9002 13.6142 10.6927 13.6174 10.4845C13.6183 9.99397 13.4765 9.51421 13.2098 9.10587C12.9431 8.69754 12.5635 8.37896 12.1191 8.19045C11.6746 8.00194 11.1853 7.95196 10.713 8.04683C10.2407 8.1417 9.80657 8.37716 9.46561 8.72342C9.12465 9.06969 8.89214 9.51121 8.7975 9.99213C8.70285 10.473 8.75032 10.9718 8.9339 11.4252C9.11748 11.8786 9.42892 12.2664 9.82883 12.5395C10.2287 12.8125 10.6992 12.9586 11.1806 12.9592C11.6017 12.9572 12.015 12.8427 12.3791 12.627L19.9544 18.633C18.5617 20.7766 18.599 23.5704 20.0483 25.6747L17.7442 28.0229C17.5579 27.9623 17.364 27.93 17.1684 27.9273C16.065 27.9283 15.1711 28.84 15.1714 29.9643C15.1716 31.0884 16.0661 31.9997 17.1695 32C18.2729 32.0003 19.1678 31.0895 19.1687 29.9653C19.1661 29.7661 19.1345 29.5684 19.0748 29.3787L21.3541 27.0555C23.3907 28.6529 26.1879 28.7905 28.3661 27.4005C30.5443 26.0104 31.6435 23.386 31.1216 20.822C30.5997 18.2578 28.5669 16.2954 26.0258 15.9023ZM25.081 25.3019C24.6599 25.3135 24.2408 25.2389 23.8485 25.0827C23.4561 24.9265 23.0985 24.6918 22.7966 24.3924C22.4948 24.093 22.2549 23.7351 22.091 23.3397C21.9272 22.9443 21.8428 22.5194 21.8428 22.0902C21.8428 21.661 21.9272 21.2362 22.091 20.8408C22.2549 20.4454 22.4948 20.0874 22.7966 19.7881C23.0985 19.4887 23.4561 19.254 23.8485 19.0978C24.2408 18.9415 24.6599 18.867 25.081 18.8786C26.7779 18.9391 28.1231 20.3578 28.1241 22.0879C28.1248 23.8178 26.7811 25.238 25.0841 25.3003" fill="white"/>
    </svg>
    }
    href="/integrations/crm/hubspot"
  >
    HubSpot CRM integration is used to sync data from Lago to HubSpot.
  </Card>
</CardGroup>

## Marketplaces & hyperscalers integrations

<Info>
  Lago integrates with marketplaces and hyperscalers through our partner
  [Suger.io](https://suger.io).
</Info>

<CardGroup cols={2}>
  <Card
    title="AWS Marketplace"
    iconType="brand"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#F3F4F6" />
       <g clip-path="url(#clip0_4694_641)">
         <path
           d="M12.5749 16.2798C12.5749 16.4766 12.5962 16.6362 12.6334 16.7532C12.6807 16.8848 12.7375 17.0128 12.8036 17.1361C12.8302 17.1787 12.8408 17.2212 12.8408 17.2585C12.8408 17.3116 12.8089 17.3648 12.7398 17.418L12.4047 17.6414C12.3568 17.6733 12.309 17.6893 12.2664 17.6893C12.2132 17.6893 12.16 17.6627 12.1068 17.6148C12.0351 17.5378 11.971 17.4541 11.9154 17.3648C11.8622 17.2745 11.8089 17.1733 11.7505 17.051C11.3356 17.5404 10.8143 17.785 10.1867 17.785C9.73999 17.785 9.3836 17.6573 9.12295 17.4021C8.86237 17.1467 8.72942 16.8063 8.72942 16.3809C8.72942 15.9288 8.88898 15.5618 9.21343 15.2852C9.53782 15.0086 9.96869 14.8703 10.5165 14.8703C10.6974 14.8703 10.8835 14.8863 11.0803 14.9129C11.2771 14.9395 11.4792 14.982 11.692 15.0299V14.6416C11.692 14.2374 11.6068 13.9555 11.4419 13.7906C11.2718 13.6257 10.9845 13.5459 10.575 13.5459C10.3888 13.5459 10.1974 13.5672 10.0006 13.6151C9.80374 13.663 9.6123 13.7215 9.42614 13.7959C9.34106 13.8332 9.27724 13.8544 9.23997 13.8651C9.2027 13.8758 9.17616 13.881 9.15489 13.881C9.08041 13.881 9.0432 13.8278 9.0432 13.7161V13.4555C9.0432 13.3704 9.05387 13.3066 9.08041 13.2694C9.10702 13.2321 9.15489 13.1949 9.22937 13.1577C9.41551 13.0619 9.63889 12.9821 9.89949 12.9183C10.1602 12.8492 10.4368 12.8173 10.7293 12.8173C11.3623 12.8173 11.825 12.9609 12.1229 13.2481C12.4154 13.5353 12.5643 13.9714 12.5643 14.5565V16.2798H12.5749ZM10.4154 17.0882C10.591 17.0882 10.7718 17.0564 10.9633 16.9925C11.1548 16.9287 11.325 16.8117 11.4686 16.6521C11.5537 16.5511 11.6175 16.4394 11.6494 16.3117C11.6813 16.1841 11.7026 16.0298 11.7026 15.849V15.6256C11.5413 15.5864 11.3779 15.5562 11.2132 15.5352C11.0474 15.5141 10.8804 15.5035 10.7133 15.5032C10.3569 15.5032 10.0963 15.5724 9.92082 15.716C9.74532 15.8596 9.66018 16.0617 9.66018 16.3276C9.66018 16.5776 9.72399 16.7638 9.85695 16.8915C9.98463 17.0244 10.1708 17.0882 10.4154 17.0882ZM14.6864 17.6627C14.5907 17.6627 14.5269 17.6467 14.4843 17.6095C14.4418 17.5776 14.4045 17.5031 14.3726 17.4021L13.1228 13.2907C13.0908 13.1842 13.0748 13.1151 13.0748 13.0779C13.0748 12.9928 13.1174 12.9449 13.2025 12.9449H13.7237C13.8248 12.9449 13.894 12.9609 13.9312 12.9981C13.9737 13.03 14.0057 13.1045 14.0375 13.2055L14.9311 16.7266L15.7608 13.2055C15.7874 13.0992 15.8194 13.03 15.8618 12.9981C15.9044 12.9662 15.9789 12.9449 16.0747 12.9449H16.5001C16.6012 12.9449 16.6704 12.9609 16.7129 12.9981C16.7555 13.03 16.7927 13.1045 16.8139 13.2055L17.6543 16.7691L18.5744 13.2055C18.6063 13.0992 18.6436 13.03 18.6808 12.9981C18.7233 12.9662 18.7925 12.9449 18.8882 12.9449H19.3828C19.468 12.9449 19.5159 12.9875 19.5159 13.0779C19.5159 13.1045 19.5105 13.1311 19.5052 13.163C19.4999 13.1948 19.4893 13.2374 19.468 13.296L18.1861 17.4074C18.1542 17.5138 18.117 17.5829 18.0744 17.6148C18.0319 17.6467 17.9627 17.668 17.8724 17.668H17.415C17.3139 17.668 17.2447 17.6521 17.2021 17.6148C17.1596 17.5776 17.1224 17.5084 17.1011 17.4021L16.2766 13.9714L15.4576 17.3967C15.431 17.5031 15.3991 17.5723 15.3566 17.6095C15.314 17.6467 15.2395 17.6627 15.1438 17.6627H14.6864ZM21.5211 17.8063C21.2445 17.8063 20.9679 17.7744 20.702 17.7105C20.436 17.6467 20.2286 17.5775 20.0904 17.4978C20.0052 17.4499 19.9467 17.3968 19.9255 17.3489C19.9048 17.3019 19.8939 17.2512 19.8935 17.1999V16.9287C19.8935 16.817 19.9361 16.7638 20.0159 16.7638C20.0485 16.7639 20.0808 16.7693 20.1116 16.7798C20.1435 16.7905 20.1914 16.8117 20.2446 16.8329C20.4324 16.9156 20.6285 16.978 20.8296 17.0191C21.038 17.0613 21.25 17.0827 21.4626 17.0829C21.7977 17.0829 22.0583 17.0244 22.2391 16.9074C22.42 16.7904 22.5157 16.6202 22.5157 16.4021C22.5157 16.2532 22.4678 16.1309 22.3721 16.0298C22.2763 15.9287 22.0955 15.8384 21.8349 15.7532L21.0637 15.5139C20.6754 15.3916 20.3882 15.2107 20.2126 14.9713C20.0372 14.7373 19.9467 14.4767 19.9467 14.2001C19.9467 13.9768 19.9946 13.78 20.0904 13.6097C20.186 13.4396 20.3137 13.2907 20.4733 13.1736C20.6329 13.0513 20.8137 12.9609 21.0265 12.8971C21.2392 12.8332 21.4625 12.8066 21.6966 12.8066C21.8136 12.8066 21.9359 12.812 22.053 12.8279C22.1753 12.8438 22.287 12.8651 22.3987 12.8864C22.505 12.913 22.6061 12.9396 22.7019 12.9715C22.7976 13.0035 22.872 13.0353 22.9252 13.0672C22.9997 13.1098 23.0529 13.1524 23.0848 13.2002C23.1167 13.2428 23.1327 13.3013 23.1327 13.3757V13.6257C23.1327 13.7374 23.0901 13.7959 23.0103 13.7959C22.9678 13.7959 22.8986 13.7746 22.8083 13.7321C22.505 13.5938 22.1646 13.5246 21.787 13.5246C21.4839 13.5246 21.2445 13.5725 21.0796 13.6736C20.9148 13.7746 20.8296 13.9289 20.8296 14.1469C20.8296 14.2959 20.8828 14.4235 20.9892 14.5246C21.0955 14.6257 21.2924 14.7267 21.5743 14.8171L22.3295 15.0565C22.7125 15.1788 22.9891 15.349 23.154 15.567C23.3188 15.7851 23.3987 16.0351 23.3987 16.3117C23.3987 16.5404 23.3507 16.7478 23.2603 16.9287C23.1646 17.1095 23.0369 17.2691 22.872 17.3968C22.7071 17.5297 22.5104 17.6255 22.2817 17.6946C22.0423 17.7691 21.7923 17.8063 21.5211 17.8063Z"
           fill="#252F3E"
         />
         <path
           d="M22.5263 20.3902C20.7765 21.6827 18.234 22.3688 16.0481 22.3688C12.9844 22.3688 10.224 21.2359 8.13904 19.353C7.97414 19.2041 8.12304 19.002 8.31981 19.119C10.575 20.4275 13.3567 21.22 16.2342 21.22C18.1756 21.22 20.3084 20.8157 22.2711 19.986C22.5636 19.853 22.8135 20.1775 22.5263 20.3902ZM23.255 19.5605C23.0317 19.2733 21.7764 19.4222 21.2073 19.4913C21.037 19.5127 21.0104 19.3637 21.1647 19.252C22.1646 18.5499 23.8082 18.7521 23.9996 18.986C24.1911 19.2254 23.9464 20.8689 23.0103 21.6561C22.8668 21.7784 22.7285 21.7146 22.7923 21.5551C23.005 21.0285 23.4784 19.8424 23.255 19.5605Z"
           fill="#FF9900"
         />
       </g>
       <defs>
         <clipPath id="clip0_4694_641">
           <rect
             width="16.128"
             height="9.6"
             fill="white"
             transform="translate(8 12.8008)"
           />
         </clipPath>
       </defs>
     </svg>
    }
    href="/integrations/marketplaces/aws-marketplace"
  >
    Quickly list, transact, and co-sell on AWS Marketplace with Lago, via
    Suger.io integration.
  </Card>

  <Card
    title="Azure Marketplace"
    iconType="brand"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#F3F4F6" />
       <path
         d="M13.3336 8.40328H18.0694L13.1532 23.081C13.1029 23.2321 13.0068 23.3635 12.8785 23.4567C12.7502 23.5498 12.5961 23.6001 12.438 23.6004H8.75239C8.63271 23.6001 8.51482 23.5712 8.40847 23.5159C8.30211 23.4606 8.21036 23.3805 8.14079 23.2824C8.07123 23.1843 8.02585 23.0709 8.00843 22.9515C7.991 22.8322 8.00203 22.7105 8.04058 22.5963L12.6218 8.91975C12.6721 8.76867 12.7682 8.63729 12.8965 8.54412C13.0248 8.45095 13.1789 8.40068 13.337 8.40039L13.3336 8.40328Z"
         fill="url(#paint0_linear_4694_660)"
       />
       <path
         d="M20.2153 18.248H12.7061C12.6363 18.248 12.5681 18.2692 12.5105 18.3088C12.4528 18.3484 12.4082 18.4045 12.3826 18.47C12.3571 18.5354 12.3516 18.6071 12.367 18.6757C12.3824 18.7443 12.418 18.8066 12.469 18.8545L17.2948 23.3932C17.4349 23.5245 17.6189 23.5978 17.8102 23.5986H22.0627L20.2153 18.248Z"
         fill="#0078D4"
       />
       <path
         d="M13.3338 8.40235C13.1742 8.40194 13.0185 8.45287 12.8896 8.54773C12.7606 8.64259 12.6651 8.77643 12.6168 8.92979L8.04422 22.5827C8.0034 22.6974 7.99058 22.8203 8.00685 22.941C8.02313 23.0618 8.06802 23.1768 8.13772 23.2763C8.20743 23.3759 8.29991 23.4571 8.40733 23.513C8.51475 23.569 8.63396 23.598 8.75488 23.5977H12.5344C12.6752 23.5724 12.8068 23.5099 12.9158 23.4165C13.0248 23.3231 13.1072 23.2023 13.1546 23.0662L14.0662 20.3581L17.3235 23.42C17.4601 23.5337 17.6313 23.5966 17.8085 23.5983H22.0461L20.1879 18.2477H14.7712L18.0868 8.40235H13.3338Z"
         fill="url(#paint1_linear_4694_660)"
       />
       <path
         d="M19.3827 8.91975C19.3324 8.76876 19.2364 8.63745 19.1082 8.54429C18.98 8.45113 18.826 8.4008 18.668 8.40039H13.3904C13.5485 8.4008 13.7024 8.45113 13.8306 8.54429C13.9588 8.63745 14.0548 8.76876 14.1051 8.91975L18.6863 22.5963C18.7246 22.7106 18.7353 22.8325 18.7176 22.9518C18.6998 23.0712 18.6542 23.1845 18.5843 23.2825C18.5145 23.3805 18.4225 23.4604 18.3159 23.5154C18.2094 23.5705 18.0914 23.5992 17.9716 23.5992H23.2498C23.3692 23.5986 23.4867 23.5694 23.5927 23.5141C23.6987 23.4587 23.7902 23.3788 23.8596 23.2809C23.929 23.183 23.9743 23.0698 23.9918 22.9508C24.0094 22.8318 23.9986 22.7103 23.9604 22.5963L19.3827 8.91975Z"
         fill="url(#paint2_linear_4694_660)"
       />
       <defs>
         <linearGradient
           id="paint0_linear_4694_660"
           x1="13.9006"
           y1="9.54585"
           x2="9.33658"
           y2="23.3545"
           gradientUnits="userSpaceOnUse"
         >
           <stop stop-color="#114A8B" />
           <stop offset="1" stop-color="#0669BC" />
         </linearGradient>
         <linearGradient
           id="paint1_linear_4694_660"
           x1="16.332"
           y1="16.5579"
           x2="15.4213"
           y2="16.7984"
           gradientUnits="userSpaceOnUse"
         >
           <stop stop-opacity="0.3" />
           <stop offset="0.071" stop-opacity="0.2" />
           <stop offset="0.321" stop-opacity="0.1" />
           <stop offset="0.623" stop-opacity="0.05" />
           <stop offset="1" stop-opacity="0" />
         </linearGradient>
         <linearGradient
           id="paint2_linear_4694_660"
           x1="17.4622"
           y1="8.98848"
           x2="22.6733"
           y2="22.5055"
           gradientUnits="userSpaceOnUse"
         >
           <stop stop-color="#3CCBF4" />
           <stop offset="1" stop-color="#2892DF" />
         </linearGradient>
       </defs>
     </svg>
    }
    href="/integrations/marketplaces/azure-marketplace"
  >
    Quickly list, transact, and co-sell on Azure Marketplace with Lago, via
    Suger.io integration.
  </Card>

  <Card
    title="GCP Marketplace"
    iconType="brand"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#F3F4F6" />
       <path
         d="M18.6254 13.1301L20.0081 11.7474L20.1002 11.1652C17.5806 8.87402 13.5752 9.13381 11.3038 11.7072C10.6729 12.422 10.2048 13.3131 9.95523 14.2332L10.4505 14.1635L13.2158 13.7074L13.4293 13.4891C14.6594 12.1381 16.7393 11.9564 18.1596 13.1058L18.6254 13.1301Z"
         fill="#EA4335"
       />
       <path
         d="M21.9778 14.1934C21.66 13.023 21.0074 11.9709 20.1002 11.166L18.1596 13.1066C18.564 13.4371 18.8881 13.8551 19.1075 14.3291C19.3268 14.8031 19.4357 15.3207 19.4259 15.8429V16.1874C20.3796 16.1874 21.1531 16.9607 21.1531 17.9145C21.1531 18.8684 20.3797 19.6223 19.4259 19.6223H15.9667L15.6271 19.9911V22.0627L15.9667 22.3877H19.4258C21.9069 22.407 23.9339 20.4308 23.9533 17.9497C23.9591 17.2093 23.7817 16.4789 23.4371 15.8236C23.0924 15.1682 22.5911 14.6082 21.9778 14.1934Z"
         fill="#4285F4"
       />
       <path
         d="M12.5123 22.3874H15.9666V19.622H12.5123C12.2678 19.6219 12.0262 19.569 11.804 19.4668L11.314 19.6172L9.92155 20.9999L9.80026 21.4705C10.5811 22.0601 11.5339 22.3917 12.5123 22.3874Z"
         fill="#34A853"
       />
       <path
         d="M12.5123 13.416C10.0312 13.4307 8.03188 15.4541 8.04667 17.9353C8.05074 18.619 8.21082 19.2928 8.51471 19.9052C8.81861 20.5177 9.25829 21.0528 9.80027 21.4696L11.804 19.4659C10.9347 19.0731 10.5484 18.0501 10.9411 17.1808C11.3339 16.3116 12.357 15.9252 13.2262 16.3179C13.6092 16.491 13.916 16.7978 14.0891 17.1808L16.0928 15.1771C15.6723 14.6273 15.1302 14.1822 14.5091 13.8767C13.8879 13.5712 13.2045 13.4135 12.5123 13.416Z"
         fill="#FBBC05"
       />
     </svg>
    }
    href="/integrations/marketplaces/gcp-marketplace"
  >
    Quickly list, transact, and co-sell on GCP Marketplace with Lago, via
    Suger.io integration.
  </Card>
</CardGroup>

## Alerting integrations

<CardGroup cols={2}>
  <Card
    title="Zapier"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#FFF3E6" />
       <g clip-path="url(#clip0_4694_681)">
         <path
           d="M10.0601 17.0488L10.057 17.0386L12.0487 15.1765V14.2793H8.85336V15.1765H10.7619L10.7651 15.1851L8.79287 17.0488V17.946H12.0808V17.0488H10.0601Z"
           fill="#201515"
         />
         <path
           d="M14.0421 14.1934C13.6735 14.1934 13.3731 14.2501 13.1409 14.3637C12.9247 14.4626 12.7425 14.6256 12.618 14.8316C12.499 15.0389 12.4242 15.2696 12.3987 15.5085L13.3682 15.6477C13.4033 15.4367 13.4734 15.2872 13.5786 15.1991C13.6982 15.1069 13.8456 15.0604 13.9952 15.0674C14.192 15.0674 14.3347 15.1212 14.4235 15.2286C14.5113 15.3361 14.556 15.4849 14.556 15.681V15.7787H13.6239C13.1493 15.7787 12.8084 15.8862 12.6012 16.1011C12.3939 16.316 12.2905 16.5997 12.2908 16.9521C12.2908 17.3131 12.3943 17.5817 12.6012 17.7579C12.8081 17.9342 13.0683 18.0217 13.3819 18.0206C13.7708 18.0206 14.07 17.884 14.2793 17.6107C14.403 17.4428 14.4913 17.2506 14.5387 17.0461H14.5739L14.7076 17.9433H15.5861V15.6713C15.5861 15.2018 15.4649 14.8381 15.2226 14.5802C14.9802 14.3223 14.5867 14.1934 14.0421 14.1934ZM14.3493 16.994C14.2099 17.1127 14.0274 17.1718 13.8001 17.1718C13.6128 17.1718 13.4827 17.1383 13.4098 17.0713C13.3742 17.0397 13.3459 17.0004 13.3269 16.9563C13.3079 16.9122 13.2986 16.8643 13.2998 16.8162C13.2977 16.7707 13.3047 16.7253 13.3204 16.6828C13.336 16.6402 13.36 16.6013 13.3908 16.5685C13.4241 16.5366 13.4635 16.5119 13.5064 16.4959C13.5494 16.4799 13.595 16.473 13.6407 16.4755H14.5576V16.5373C14.5595 16.6247 14.5417 16.7113 14.5056 16.7904C14.4694 16.8696 14.416 16.9393 14.3493 16.994Z"
           fill="#201515"
         />
         <path
           d="M20.8979 14.2793H19.86V17.9465H20.8979V14.2793Z"
           fill="#201515"
         />
         <path
           d="M27.0257 14.2793C26.7325 14.2793 26.5014 14.385 26.3324 14.5963C26.211 14.7481 26.1188 14.9725 26.0556 15.2694H26.0251L25.8894 14.2793H25.003V17.946H26.0409V16.0656C26.0409 15.8285 26.0953 15.6467 26.204 15.5203C26.3127 15.3939 26.5133 15.3307 26.8058 15.3307H27.1998V14.2793H27.0257Z"
           fill="#201515"
         />
         <path
           d="M23.974 14.398C23.7317 14.2508 23.426 14.1774 23.0571 14.1777C22.4763 14.1777 22.0218 14.3466 21.6935 14.6844C21.3653 15.0221 21.2011 15.4877 21.2011 16.0812C21.1928 16.44 21.2695 16.7955 21.4247 17.1175C21.5668 17.4044 21.7881 17.6426 22.0613 17.8025C22.3362 17.9648 22.6632 18.0461 23.0423 18.0464C23.3703 18.0464 23.6442 17.9948 23.8641 17.8917C24.0708 17.799 24.2508 17.6538 24.387 17.4699C24.5166 17.2894 24.6129 17.0862 24.671 16.8704L23.7767 16.6146C23.7391 16.755 23.6666 16.8831 23.5663 16.9864C23.4653 17.0896 23.2961 17.1411 23.0586 17.1411C22.7764 17.1411 22.5659 17.0586 22.4274 16.8935C22.3269 16.7742 22.2638 16.6039 22.2359 16.3831H24.6847C24.6947 16.28 24.7 16.1935 24.7 16.1236V15.8953C24.7059 15.5886 24.6438 15.2844 24.5185 15.0056C24.4012 14.7516 24.2113 14.5398 23.974 14.398ZM23.0271 15.0518C23.448 15.0518 23.6866 15.2633 23.7431 15.6863H22.2543C22.278 15.5452 22.3352 15.4121 22.4211 15.299C22.5575 15.1338 22.7595 15.0515 23.0271 15.0518Z"
           fill="#201515"
         />
         <path
           d="M20.3901 12.8011C20.312 12.7984 20.2342 12.8118 20.1612 12.8404C20.0883 12.869 20.0218 12.9123 19.9656 12.9677C19.9101 13.0236 19.8667 13.0907 19.838 13.1647C19.8093 13.2387 19.7959 13.3179 19.7988 13.3975C19.796 13.4775 19.8094 13.5573 19.8381 13.6318C19.8669 13.7063 19.9103 13.774 19.9658 13.8306C20.0213 13.8872 20.0876 13.9315 20.1606 13.9608C20.2336 13.9901 20.3117 14.0037 20.3901 14.0008C20.4679 14.0038 20.5456 13.9902 20.6181 13.9609C20.6905 13.9315 20.7562 13.8871 20.8109 13.8305C20.8652 13.7732 20.9076 13.7053 20.9355 13.6309C20.9635 13.5565 20.9764 13.4771 20.9735 13.3975C20.9771 13.3183 20.9645 13.2392 20.9364 13.1653C20.9084 13.0914 20.8656 13.0243 20.8108 12.9682C20.7559 12.9121 20.6902 12.8684 20.6179 12.8397C20.5455 12.811 20.4681 12.7981 20.3906 12.8017L20.3901 12.8011Z"
           fill="#201515"
         />
         <path
           d="M18.2463 14.1777C17.8928 14.1777 17.6087 14.2911 17.3941 14.5178C17.2352 14.6858 17.1186 14.9365 17.0442 15.2699H17.0111L16.8754 14.2798H15.9889V18.9989H17.0269V17.0552H17.0648C17.0964 17.1848 17.1408 17.3108 17.1973 17.4312C17.2851 17.6275 17.4291 17.7919 17.6103 17.9029C17.7981 18.0076 18.0097 18.0597 18.2237 18.0539C18.6582 18.0539 18.9891 17.8811 19.2164 17.5355C19.4436 17.1898 19.5573 16.7076 19.5573 16.0887C19.5573 15.4909 19.4473 15.023 19.2274 14.6849C19.0075 14.3468 18.6805 14.1777 18.2463 14.1777ZM18.3515 16.8349C18.2305 17.014 18.0411 17.1035 17.7834 17.1035C17.6771 17.1085 17.5711 17.0876 17.4744 17.0425C17.3776 16.9974 17.2927 16.9293 17.2268 16.844C17.0925 16.6718 17.0255 16.4359 17.0258 16.1365V16.0667C17.0258 15.7626 17.0928 15.5298 17.2268 15.3683C17.3608 15.2067 17.5463 15.1269 17.7834 15.1286C18.0457 15.1286 18.2363 15.2137 18.3552 15.3838C18.4741 15.554 18.5335 15.7912 18.5335 16.0957C18.5342 16.4105 18.4739 16.6569 18.3525 16.8349H18.3515Z"
           fill="#201515"
         />
         <path
           d="M8.39091 17.0488H4.8V17.9471H8.39091V17.0488Z"
           fill="#FF4F00"
         />
       </g>
       <defs>
         <clipPath id="clip0_4694_681">
           <rect
             width="22.4"
             height="6.22222"
             fill="white"
             transform="translate(4.8 12.8008)"
           />
         </clipPath>
       </defs>
     </svg>
    }
    href="/integrations/alerting/zapier"
  >
    Use Zapier and Lago to trigger billing automations, such as an invoice
    alerting system.
  </Card>

  <Card
    title="N8N"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#ED6C5D" />
       <path
         d="M23.6333 11.1992C22.7108 11.1992 21.9404 11.8415 21.7275 12.7117H18.9803C17.9058 12.7117 17.0238 13.6026 17.0238 14.711C17.0238 15.26 16.5879 15.7055 16.0506 15.7055H15.6553C15.4424 14.8353 14.6618 14.193 13.7495 14.193C12.827 14.193 12.0566 14.8353 11.8437 15.7055H10.2724C10.0595 14.8353 9.27897 14.193 8.36662 14.193C7.28194 14.193 6.4 15.0943 6.4 16.2027C6.4 17.3112 7.28194 18.2124 8.36662 18.2124C9.28911 18.2124 10.0595 17.5702 10.2724 16.7H11.8437C12.0566 17.5702 12.8371 18.2124 13.7495 18.2124C14.6618 18.2124 15.4323 17.5805 15.6553 16.7103H16.0506C16.5879 16.7103 17.0238 17.1558 17.0238 17.7048C17.0238 18.8029 17.8956 19.7042 18.9803 19.7042H19.619C19.8318 20.5743 20.6124 21.2166 21.5247 21.2166C22.6094 21.2166 23.4914 20.3154 23.4914 19.2069C23.4914 18.0985 22.6094 17.1972 21.5247 17.1972C20.6023 17.1972 19.8318 17.8395 19.619 18.7097H18.9803C18.443 18.7097 18.0071 18.2642 18.0071 17.7152C18.0071 17.1143 17.7436 16.5757 17.3279 16.2131C17.7436 15.8505 18.0071 15.3118 18.0071 14.711C18.0071 14.162 18.443 13.7165 18.9803 13.7165H21.7275C21.9404 14.5867 22.7209 15.229 23.6333 15.229C24.718 15.229 25.5999 14.3277 25.5999 13.2193C25.6101 12.1108 24.718 11.1992 23.6333 11.1992ZM8.36662 17.2283C7.81921 17.2283 7.37317 16.7725 7.37317 16.2131C7.37317 15.6537 7.81921 15.1979 8.36662 15.1979C8.91403 15.1979 9.36007 15.6537 9.36007 16.2131C9.37021 16.7725 8.92417 17.2283 8.36662 17.2283ZM13.7495 17.2283C13.2021 17.2283 12.756 16.7725 12.756 16.2131C12.756 15.6537 13.2021 15.1979 13.7495 15.1979C14.2969 15.1979 14.7429 15.6537 14.7429 16.2131C14.7531 16.7725 14.307 17.2283 13.7495 17.2283ZM21.5247 18.2021C22.0722 18.2021 22.5182 18.6579 22.5182 19.2173C22.5182 19.7767 22.0722 20.2325 21.5247 20.2325C20.9773 20.2325 20.5313 19.7767 20.5313 19.2173C20.5313 18.6579 20.9773 18.2021 21.5247 18.2021ZM23.6333 14.2345C23.0859 14.2345 22.6398 13.7787 22.6398 13.2193C22.6398 12.6599 23.0859 12.2041 23.6333 12.2041C24.1807 12.2041 24.6267 12.6599 24.6267 13.2193C24.6267 13.7787 24.1807 14.2345 23.6333 14.2345Z"
         fill="white"
       />
     </svg>
    }
    href="/integrations/alerting/n8n"
  >
    Use n8n and Lago to trigger billing automations, such as an overconsumption
    alerting system.
  </Card>
</CardGroup>

## Data integrations

<CardGroup cols={2}>
  <Card
    title="Airbyte (ETL)"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#615EFF" />
       <path
         fill-rule="evenodd"
         clip-rule="evenodd"
         d="M13.4556 9.94139C15.2255 8.01813 18.1562 7.45399 20.5657 8.56409C23.7669 10.039 24.935 13.7963 23.1919 16.695L19.2711 23.2076C19.0519 23.5717 18.6914 23.8371 18.2686 23.9459C17.8459 24.0547 17.3953 23.998 17.0159 23.7882L21.7627 15.9018C23.0274 13.798 22.1815 11.0714 19.8605 9.99805C18.1189 9.19258 15.9903 9.59479 14.7036 10.9801C13.9941 11.7405 13.5956 12.7226 13.5822 13.7435C13.5688 14.7647 13.9417 15.7556 14.6313 16.5331C14.7553 16.6726 14.8888 16.8041 15.0305 16.9265L12.2593 21.539C12.1508 21.7194 12.0066 21.8772 11.8348 22.0041C11.6626 22.1307 11.4666 22.2238 11.2572 22.2776C11.0479 22.3315 10.8294 22.3451 10.6146 22.3182C10.3998 22.2909 10.1926 22.2234 10.0045 22.1195L13.013 17.1122C12.5808 16.5138 12.2705 15.8423 12.0984 15.1334L10.2552 18.2076C10.036 18.5717 9.67545 18.8372 9.2527 18.9459C8.82995 19.0547 8.37936 18.9981 8 18.7882L12.7674 10.8574C12.966 10.5314 13.1963 10.2247 13.4556 9.94139ZM18.9583 12.4659C20.1065 13.1027 20.5028 14.5189 19.8385 15.6213L15.2671 23.2069C15.0479 23.571 14.6874 23.8364 14.2646 23.9452C13.8419 24.054 13.3913 23.9973 13.0119 23.7875L17.2568 16.7251C16.9161 16.6562 16.5953 16.5173 16.3162 16.3176C16.037 16.1179 15.8063 15.8626 15.6399 15.5692C15.4735 15.2754 15.3755 14.9508 15.3524 14.6171C15.3293 14.2835 15.3821 13.9491 15.5068 13.6372C15.6316 13.3252 15.8251 13.0426 16.0746 12.8093C16.3241 12.576 16.6232 12.3977 16.9512 12.2864C17.2796 12.1752 17.6289 12.1336 17.9753 12.1644C18.3218 12.1952 18.657 12.298 18.9583 12.4659ZM17.2955 13.8914C17.217 13.9495 17.1508 14.0215 17.1016 14.1041H17.1013C17.0268 14.2282 16.9921 14.3706 17.0018 14.5136C17.0116 14.6567 17.0655 14.7934 17.1562 14.9071C17.247 15.0207 17.371 15.1061 17.5121 15.1519C17.6535 15.1981 17.8057 15.2026 17.9497 15.1655C18.094 15.1285 18.2231 15.0512 18.3214 14.9435C18.4198 14.8357 18.4827 14.7025 18.5022 14.5605C18.5218 14.4185 18.4968 14.274 18.431 14.1453C18.3652 14.017 18.2607 13.91 18.1316 13.8383C18.0459 13.7907 17.9511 13.7599 17.8527 13.7473C17.7544 13.7351 17.6546 13.741 17.5591 13.7659C17.4636 13.791 17.3739 13.8334 17.2955 13.8914Z"
         fill="white"
       />
     </svg>
    }
    href="/integrations/data/airbyte"
  >
    Send billing data to any warehouses by using our integration with Airbyte
    ETL services.
  </Card>
</CardGroup>

## Entitlements integrations

<CardGroup cols={2}>
  <Card
    title="Oso"
    icon={
     <svg
       width="32"
       height="32"
       viewBox="0 0 32 32"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="32" height="32" rx="8" fill="#3D2798" />
       <g clip-path="url(#clip0_4694_719)">
         <path
           d="M20.883 18.1542C20.592 18.1542 20.301 18.1542 20.01 18.1542C19.5634 18.1518 19.3466 17.9898 19.2297 17.5505C19.0905 17.0279 18.9698 16.5005 18.8272 15.979C18.7355 15.6423 18.5992 15.327 18.3422 15.0735C18.1933 14.9231 18.092 14.7318 18.0512 14.5238C18.01 14.3384 17.8538 14.2776 17.7297 14.405C17.4212 14.7227 17.0105 14.8619 16.638 15.0648C16.0497 15.3849 15.5541 15.7887 15.2655 16.4134C15.1283 16.7102 15.1831 16.8902 15.49 17.0007C15.6591 17.0532 15.8313 17.0951 16.0056 17.1262C16.2873 17.1904 16.4862 17.3486 16.5662 17.6327C16.6176 17.8137 16.5662 17.9431 16.3722 18.0132C16.123 18.1076 15.8588 18.156 15.5924 18.1557C15.0919 18.1518 14.5914 18.1557 14.0889 18.1557C13.5254 18.1557 13.2271 17.892 13.1718 17.3223C13.0904 16.4777 13.2436 15.6978 13.8159 15.0356C13.9081 14.9291 14.0855 14.8147 13.9769 14.6464C13.8799 14.5004 13.6971 14.5447 13.5487 14.5729C12.8605 14.7043 12.1573 14.8011 11.6088 15.2998C11.1766 15.689 10.7547 16.0923 10.5268 16.6475C10.3963 16.9657 10.4298 17.044 10.7552 17.1827C10.8886 17.2386 11.0263 17.2848 11.1607 17.3388C11.3212 17.4035 11.4381 17.5038 11.4332 17.6964C11.4284 17.8891 11.3275 18.0136 11.1577 18.0857C10.9749 18.1645 10.778 18.164 10.5855 18.165C10.1005 18.1679 9.61551 18.1616 9.13296 18.1557C8.98746 18.1557 8.84585 18.1406 8.7217 18.0418C8.61791 17.9601 8.49424 17.9684 8.37833 18.0224C7.49906 18.4311 6.54026 18.0448 6.14743 17.1262C5.97429 16.72 5.9258 16.3127 6.14307 15.9099C6.45685 15.3309 6.48256 14.6867 6.57228 14.0582C6.60648 13.8563 6.57518 13.6488 6.48303 13.4661C5.7318 12.0692 6.55045 10.0715 7.93458 9.2858C8.86768 8.75548 9.82987 8.29133 10.8929 8.06947C11.5772 7.92643 12.2412 8.0364 12.908 8.16143C13.8668 8.34048 14.8179 8.56039 15.7922 8.64796C16.218 8.69189 16.6469 8.69596 17.0735 8.66013C17.9912 8.5705 18.9176 8.66156 19.8005 8.92819C20.5959 9.16513 21.4136 9.11308 22.2254 9.08389C22.3383 9.07693 22.4451 9.03064 22.5276 8.95302C22.867 8.66889 23.2526 8.71801 23.5286 9.07513C23.6037 9.17243 23.7119 9.20358 23.8142 9.24591C24.5032 9.5233 25.1466 9.90333 25.7226 10.3732C26.097 10.6831 26.0941 10.8904 25.6605 11.1336C25.3928 11.284 25.2182 11.4465 25.2624 11.7734C25.2822 11.9194 25.1678 11.9432 25.0684 11.968C24.0291 12.24 22.9771 12.44 21.9029 12.5115C21.5485 12.531 21.1956 12.5734 20.8466 12.6385C20.6526 12.6769 20.5639 12.7844 20.5377 12.979C20.3665 14.2815 20.7462 15.455 21.3665 16.5725C21.4592 16.7389 21.6367 16.7983 21.7991 16.8645C22.0067 16.9516 22.2225 17.0187 22.4296 17.1077C22.6512 17.2011 22.8176 17.3544 22.8176 17.6142C22.8176 17.874 22.6056 17.9548 22.4155 18.0433C22.1667 18.1601 21.9 18.1635 21.6328 18.163H20.8825L20.883 18.1542ZM8.35844 17.4313C8.42973 17.1909 8.50055 16.9768 8.55681 16.7584C8.67902 16.2816 8.82305 15.8092 8.85554 15.3134C8.86136 15.2224 8.85556 15.1295 8.75468 15.0886C8.66157 15.0517 8.59463 15.11 8.54904 15.1767C8.27988 15.5688 7.97484 15.9366 7.74544 16.356C7.70525 16.4223 7.68463 16.4986 7.686 16.5761C7.68738 16.6536 7.71067 16.7292 7.75319 16.7939C7.90638 17.0479 8.11293 17.2654 8.35844 17.4313Z"
           fill="#FDFDFE"
         />
         <path
           d="M12.455 22.1449C12.455 22.9997 12.086 23.6045 11.4444 23.8545C10.6776 24.1508 9.80513 23.9908 9.325 23.4322C8.80219 22.8241 8.78765 22.1089 9.0379 21.399C9.26244 20.7626 9.77604 20.4347 10.4409 20.3773C11.1931 20.3097 11.8319 20.5179 12.2354 21.2098C12.3965 21.4938 12.4728 21.8185 12.455 22.1449ZM11.7334 22.1784C11.7819 21.3416 11.1432 20.8595 10.3953 21.0361C9.96516 21.1378 9.70668 21.4307 9.64703 21.8607C9.57865 22.3531 9.58785 22.8479 10.0607 23.1685C10.4249 23.4162 10.827 23.4186 11.2101 23.2206C11.6228 23.007 11.7421 22.6197 11.7315 22.1784H11.7334Z"
           fill="#FAFAFC"
         />
         <path
           d="M21.368 22.1756C21.3728 23.2878 20.6856 23.988 19.5852 23.9904C18.5061 23.9933 17.8194 23.2947 17.8136 22.1878C17.8078 21.0809 18.4877 20.3692 19.5595 20.3633C20.6774 20.3575 21.3631 21.0445 21.368 22.1756ZM18.5347 22.1678C18.5289 22.5571 18.6065 22.9137 18.9474 23.1506C19.3194 23.409 19.7263 23.4226 20.1172 23.2212C20.5944 22.975 20.6701 22.5216 20.6449 22.036C20.6226 21.6074 20.4509 21.2746 20.044 21.0902C20.0151 21.0763 19.9855 21.0641 19.9552 21.0537C19.1797 20.8012 18.5367 21.3057 18.5347 22.1678Z"
           fill="#FAFAFC"
         />
         <path
           d="M15.0521 20.3633C15.6923 20.357 16.1603 20.5638 16.4542 21.0965C16.5439 21.26 16.526 21.3636 16.3203 21.3884C16.2564 21.3973 16.1939 21.4146 16.1346 21.44C15.9673 21.5101 15.8664 21.5086 15.7781 21.2979C15.6186 20.9175 14.8644 20.8114 14.5739 21.1062C14.3867 21.295 14.4512 21.5811 14.7107 21.7003C14.941 21.8068 15.1956 21.82 15.4381 21.8711C15.652 21.9112 15.8615 21.972 16.0638 22.0526C16.3936 22.1902 16.6176 22.4189 16.6506 22.7872C16.6855 23.1764 16.5657 23.5044 16.2301 23.733C15.6559 24.1222 14.5671 24.0624 14.0424 23.6094C13.8484 23.4361 13.7128 23.2066 13.6544 22.9526C13.6311 22.8641 13.6316 22.7926 13.7514 22.7823C13.7994 22.7759 13.8465 22.7643 13.892 22.7478C14.1268 22.6748 14.2975 22.6174 14.4149 22.9677C14.5657 23.4158 15.4023 23.5627 15.7815 23.2635C16.0337 23.0645 15.9988 22.7381 15.7088 22.5994C15.4798 22.4899 15.2281 22.468 14.9813 22.4199C14.7673 22.3814 14.5582 22.3189 14.3581 22.2335C13.9861 22.0676 13.7625 21.7927 13.7669 21.3719C13.7713 20.951 13.9895 20.6552 14.3712 20.4874C14.5855 20.3938 14.8186 20.3513 15.0521 20.3633Z"
           fill="#FAF9FC"
         />
       </g>
       <defs>
         <clipPath id="clip0_4694_719">
           <rect
             width="20"
             height="16"
             fill="white"
             transform="translate(6 8)"
           />
         </clipPath>
       </defs>
     </svg>
    }
    href="/integrations/entitlements/osohq"
  >
    Oso is an Authorization as service used for entitlements
  </Card>
</CardGroup>


# AWS Marketplace

Lago integrates with AWS marketplace through our partner Suger.io

If you're using Lago for metering and billing and looking to expand into AWS marketplace, [Suger](https://suger.io) is the ideal partner. Suger offers the fastest and easiest way to list, transact, and co-sell on AWS marketplace.

Their no-code, fully automated integration with Lago allows you to seamlessly track usage within your existing setup and allocate it across various cloud marketplaces.
This approach eliminates the need for migration or complex engineering, ensuring a smooth and hassle-free transition.

<CardGroup cols={2}>
  <Card
    title="Documentation"
    iconType="brand"
    icon={<svg width="30" height="30" viewBox="0 0 40 40" fill="none" xmlns="http://www.w3.org/2000/svg">
    <rect width="40" height="40" rx="12" fill="#F3F4F6"/>
    <g clip-path="url(#clip0_3012_1142)">
    <path d="M15.7186 20.3481C15.7186 20.5941 15.7452 20.7936 15.7917 20.9398C15.8508 21.1044 15.9219 21.2644 16.0044 21.4185C16.0377 21.4717 16.051 21.5248 16.051 21.5714C16.051 21.6379 16.0111 21.7044 15.9247 21.7709L15.5059 22.0501C15.446 22.09 15.3862 22.1099 15.3329 22.1099C15.2665 22.1099 15.2 22.0767 15.1335 22.0168C15.0439 21.9206 14.9638 21.816 14.8942 21.7044C14.8277 21.5914 14.7612 21.465 14.6881 21.3121C14.1694 21.9238 13.5179 22.2296 12.7334 22.2296C12.175 22.2296 11.7295 22.07 11.4037 21.751C11.0779 21.4318 10.9117 21.0063 10.9117 20.4744C10.9117 19.9093 11.1112 19.4506 11.5168 19.1048C11.9223 18.7591 12.4608 18.5863 13.1456 18.5863C13.3717 18.5863 13.6044 18.6062 13.8503 18.6394C14.0964 18.6727 14.349 18.7259 14.615 18.7857V18.3004C14.615 17.795 14.5085 17.4427 14.3024 17.2366C14.0897 17.0305 13.7306 16.9307 13.2187 16.9307C12.986 16.9307 12.7467 16.9574 12.5007 17.0172C12.2546 17.0771 12.0154 17.1502 11.7826 17.2433C11.6763 17.2898 11.5965 17.3164 11.5499 17.3297C11.5034 17.343 11.4702 17.3496 11.4436 17.3496C11.3505 17.3496 11.304 17.2831 11.304 17.1435V16.8177C11.304 16.7114 11.3173 16.6316 11.3505 16.5851C11.3837 16.5385 11.4436 16.492 11.5367 16.4455C11.7694 16.3257 12.0486 16.226 12.3743 16.1463C12.7002 16.0598 13.0459 16.02 13.4116 16.02C14.2028 16.02 14.7812 16.1994 15.1535 16.5585C15.5192 16.9175 15.7054 17.4627 15.7054 18.194V20.3481H15.7186ZM13.0193 21.3587C13.2387 21.3587 13.4648 21.3188 13.7041 21.239C13.9434 21.1592 14.1562 21.0129 14.3357 20.8135C14.4421 20.6872 14.5219 20.5476 14.5617 20.388C14.6016 20.2285 14.6282 20.0356 14.6282 19.8096V19.5303C14.4266 19.4813 14.2224 19.4436 14.0165 19.4173C13.8092 19.391 13.6005 19.3777 13.3916 19.3774C12.9461 19.3774 12.6204 19.4638 12.401 19.6434C12.1816 19.8229 12.0752 20.0755 12.0752 20.4079C12.0752 20.7204 12.155 20.9531 12.3212 21.1127C12.4808 21.2789 12.7135 21.3587 13.0193 21.3587ZM18.358 22.0767C18.2383 22.0767 18.1586 22.0568 18.1054 22.0102C18.0522 21.9703 18.0056 21.8772 17.9658 21.751L16.4034 16.6117C16.3634 16.4787 16.3435 16.3922 16.3435 16.3457C16.3435 16.2394 16.3967 16.1794 16.5031 16.1794H17.1546C17.2809 16.1794 17.3674 16.1994 17.4139 16.2459C17.4671 16.2859 17.507 16.379 17.5469 16.5052L18.6638 20.9066L19.701 16.5052C19.7343 16.3723 19.7742 16.2859 19.8273 16.2459C19.8805 16.2061 19.9736 16.1795 20.0933 16.1795H20.6252C20.7514 16.1795 20.8379 16.1994 20.891 16.2459C20.9443 16.2859 20.9908 16.379 21.0174 16.5052L22.0679 20.9598L23.218 16.5052C23.2579 16.3723 23.3044 16.2859 23.351 16.2459C23.4041 16.2061 23.4906 16.1795 23.6103 16.1795H24.2285C24.335 16.1795 24.3948 16.2327 24.3948 16.3457C24.3948 16.379 24.3881 16.4122 24.3815 16.4521C24.3748 16.4919 24.3615 16.5452 24.335 16.6183L22.7326 21.7576C22.6928 21.8906 22.6462 21.977 22.593 22.0168C22.5398 22.0568 22.4534 22.0834 22.3404 22.0834H21.7687C21.6423 22.0834 21.5559 22.0634 21.5026 22.0168C21.4495 21.9703 21.403 21.8839 21.3764 21.751L20.3458 17.4627L19.3219 21.7442C19.2888 21.8772 19.2488 21.9637 19.1957 22.0102C19.1425 22.0568 19.0494 22.0767 18.9298 22.0767H18.358ZM26.9013 22.2562C26.5556 22.2562 26.2099 22.2163 25.8775 22.1365C25.545 22.0568 25.2858 21.9703 25.1129 21.8707C25.0065 21.8107 24.9333 21.7443 24.9068 21.6845C24.8809 21.6258 24.8674 21.5624 24.8669 21.4983V21.1592C24.8669 21.0196 24.9201 20.9531 25.0198 20.9531C25.0605 20.9532 25.101 20.96 25.1395 20.9731C25.1794 20.9864 25.2392 21.0129 25.3057 21.0395C25.5405 21.1429 25.7857 21.2209 26.037 21.2722C26.2974 21.325 26.5625 21.3517 26.8282 21.352C27.247 21.352 27.5728 21.2789 27.7989 21.1326C28.0249 20.9863 28.1446 20.7736 28.1446 20.501C28.1446 20.3149 28.0848 20.1619 27.9651 20.0356C27.8454 19.9092 27.6194 19.7963 27.2936 19.6899L26.3295 19.3907C25.8442 19.2378 25.4852 19.0118 25.2658 18.7125C25.0464 18.42 24.9334 18.0943 24.9334 17.7485C24.9334 17.4693 24.9932 17.2233 25.1129 17.0105C25.2325 16.7978 25.3921 16.6117 25.5916 16.4654C25.791 16.3125 26.0171 16.1994 26.283 16.1197C26.5489 16.0399 26.8281 16.0067 27.1207 16.0067C27.267 16.0067 27.4199 16.0133 27.5662 16.0332C27.7191 16.0532 27.8587 16.0798 27.9983 16.1063C28.1313 16.1396 28.2576 16.1728 28.3773 16.2128C28.4969 16.2527 28.59 16.2925 28.6565 16.3324C28.7496 16.3856 28.8161 16.4388 28.856 16.4987C28.8959 16.5518 28.9158 16.625 28.9158 16.718V17.0305C28.9158 17.1701 28.8626 17.2433 28.7629 17.2433C28.7097 17.2433 28.6233 17.2166 28.5103 17.1634C28.1312 16.9906 27.7057 16.9041 27.2338 16.9041C26.8548 16.9041 26.5556 16.964 26.3495 17.0903C26.1434 17.2166 26.037 17.4095 26.037 17.682C26.037 17.8682 26.1035 18.0278 26.2364 18.1541C26.3694 18.2805 26.6154 18.4067 26.9678 18.5198L27.9119 18.819C28.3906 18.9719 28.7363 19.1846 28.9424 19.4572C29.1485 19.7297 29.2483 20.0423 29.2483 20.388C29.2483 20.6739 29.1884 20.9332 29.0754 21.1592C28.9557 21.3852 28.7961 21.5847 28.59 21.7443C28.3839 21.9105 28.1379 22.0302 27.8521 22.1166C27.5528 22.2097 27.2404 22.2562 26.9013 22.2562Z" fill="#252F3E"/>
    <path d="M28.1579 25.4874C25.9706 27.103 22.7925 27.9607 20.0601 27.9607C16.2305 27.9607 12.78 26.5445 10.1738 24.1909C9.96767 24.0048 10.1538 23.7522 10.3997 23.8984C13.2187 25.534 16.6959 26.5246 20.2928 26.5246C22.7194 26.5246 25.3855 26.0193 27.8388 24.9821C28.2045 24.8159 28.5169 25.2215 28.1579 25.4874ZM29.0688 24.4502C28.7895 24.0912 27.2204 24.2774 26.5091 24.3638C26.2963 24.3905 26.263 24.2043 26.4559 24.0647C27.7058 23.187 29.7602 23.4397 29.9995 23.7322C30.2389 24.0314 29.933 26.0857 28.7629 27.0697C28.5834 27.2227 28.4106 27.1429 28.4903 26.9435C28.7562 26.2852 29.348 24.8026 29.0688 24.4502Z" fill="#FF9900"/>
    </g>
    <defs>
    <clipPath id="clip0_3012_1142">
    <rect width="20.16" height="12" fill="white" transform="translate(10 16)"/>
    </clipPath>
    </defs>
    </svg>
    }
    href="https://doc.suger.io/integrations/lago"
  >
    Quickly list, transact, and co-sell on AWS Marketplace with Lago, via Suger.io integration.
  </Card>
</CardGroup>


# Azure Marketplace

Lago integrates with Azure marketplace through our partner Suger.io

If you're using Lago for metering and billing and looking to expand into Azure marketplace, [Suger](https://suger.io) is the ideal partner. Suger offers the fastest and easiest way to list, transact, and co-sell on Azure marketplace.

Their no-code, fully automated integration with Lago allows you to seamlessly track usage within your existing setup and allocate it across various cloud marketplaces.
This approach eliminates the need for migration or complex engineering, ensuring a smooth and hassle-free transition.

<CardGroup cols={2}>
  <Card
    title="Documentation"
    iconType="brand"
    icon={
     <svg
       width="30"
       height="30"
       viewBox="0 0 40 40"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="40" height="40" rx="12" fill="#F3F4F6" />
       <path
         d="M17.6715 13.417H21.8065L17.514 26.1345C17.47 26.2654 17.3862 26.3792 17.2741 26.46C17.1621 26.5407 17.0276 26.5842 16.8895 26.5845H13.6715C13.567 26.5843 13.4641 26.5592 13.3712 26.5113C13.2783 26.4633 13.1982 26.394 13.1375 26.309C13.0767 26.224 13.0371 26.1257 13.0219 26.0223C13.0067 25.9189 13.0163 25.8134 13.05 25.7145L17.05 13.8645C17.0939 13.7336 17.1778 13.6197 17.2898 13.539C17.4019 13.4583 17.5364 13.4147 17.6745 13.4145L17.6715 13.417Z"
         fill="url(#paint0_linear_3012_1160)"
       />
       <path
         d="M23.68 21.947H17.1235C17.0626 21.947 17.003 21.9653 16.9527 21.9996C16.9023 22.0339 16.8634 22.0826 16.8411 22.1393C16.8187 22.196 16.814 22.2581 16.8274 22.3175C16.8409 22.377 16.8719 22.431 16.9165 22.4725L21.13 26.405C21.2523 26.5188 21.413 26.5823 21.58 26.583H25.293L23.68 21.947Z"
         fill="#0078D4"
       />
       <path
         d="M17.6715 13.417C17.5321 13.4166 17.3963 13.4608 17.2837 13.543C17.1711 13.6252 17.0877 13.7411 17.0455 13.874L13.053 25.7035C13.0174 25.8029 13.0062 25.9094 13.0204 26.014C13.0346 26.1186 13.0738 26.2183 13.1347 26.3045C13.1955 26.3908 13.2763 26.4611 13.3701 26.5096C13.4639 26.5581 13.5679 26.5833 13.6735 26.583H16.9735C17.0965 26.5611 17.2114 26.5069 17.3066 26.426C17.4017 26.3451 17.4736 26.2403 17.515 26.1225L18.311 23.776L21.155 26.429C21.2743 26.5275 21.4238 26.582 21.5785 26.5835H25.2785L23.656 21.9475H18.9265L21.8215 13.417H17.6715Z"
         fill="url(#paint1_linear_3012_1160)"
       />
       <path
         d="M22.953 13.8645C22.9091 13.7337 22.8253 13.6199 22.7134 13.5392C22.6014 13.4584 22.467 13.4148 22.329 13.4145H17.721C17.859 13.4148 17.9934 13.4584 18.1054 13.5392C18.2173 13.6199 18.3011 13.7337 18.345 13.8645L22.345 25.7145C22.3784 25.8136 22.3878 25.9191 22.3723 26.0225C22.3568 26.1259 22.3169 26.2242 22.2559 26.3091C22.195 26.394 22.1146 26.4632 22.0216 26.5109C21.9286 26.5586 21.8256 26.5835 21.721 26.5835H26.3295C26.4338 26.5829 26.5364 26.5577 26.629 26.5097C26.7215 26.4617 26.8014 26.3925 26.862 26.3077C26.9226 26.2228 26.9621 26.1248 26.9774 26.0217C26.9927 25.9186 26.9833 25.8133 26.95 25.7145L22.953 13.8645Z"
         fill="url(#paint2_linear_3012_1160)"
       />
       <defs>
         <linearGradient
           id="paint0_linear_3012_1160"
           x1="18.1666"
           y1="14.407"
           x2="14.2364"
           y2="26.3895"
           gradientUnits="userSpaceOnUse"
         >
           <stop stop-color="#114A8B" />
           <stop offset="1" stop-color="#0669BC" />
         </linearGradient>
         <linearGradient
           id="paint1_linear_3012_1160"
           x1="20.2893"
           y1="20.4833"
           x2="19.495"
           y2="20.6948"
           gradientUnits="userSpaceOnUse"
         >
           <stop stop-opacity="0.3" />
           <stop offset="0.071" stop-opacity="0.2" />
           <stop offset="0.321" stop-opacity="0.1" />
           <stop offset="0.623" stop-opacity="0.05" />
           <stop offset="1" stop-opacity="0" />
         </linearGradient>
         <linearGradient
           id="paint2_linear_3012_1160"
           x1="21.2762"
           y1="13.924"
           x2="25.7656"
           y2="25.659"
           gradientUnits="userSpaceOnUse"
         >
           <stop stop-color="#3CCBF4" />
           <stop offset="1" stop-color="#2892DF" />
         </linearGradient>
       </defs>
     </svg>
    }
    href="https://doc.suger.io/integrations/lago"
  >
    Quickly list, transact, and co-sell on Azure Marketplace with Lago, via
    Suger.io integration.
  </Card>
</CardGroup>


# GCP Marketplace

Lago integrates with GCP marketplace through our partner Suger.io

If you're using Lago for metering and billing and looking to expand into GCP marketplace, [Suger](https://suger.io) is the ideal partner. Suger offers the fastest and easiest way to list, transact, and co-sell on GCP marketplace.

Their no-code, fully automated integration with Lago allows you to seamlessly track usage within your existing setup and allocate it across various cloud marketplaces.
This approach eliminates the need for migration or complex engineering, ensuring a smooth and hassle-free transition.

<CardGroup cols={2}>
  <Card
    title="Documentation"
    iconType="brand"
    icon={
     <svg
       width="30"
       height="30"
       viewBox="0 0 40 40"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="40" height="40" rx="12" fill="#F3F4F6" />
       <g clip-path="url(#clip0_3012_1182)">
         <path
           d="M21.9613 17.3098L23.2576 16.0135L23.3439 15.4677C20.9817 13.3198 17.2267 13.5633 15.0973 15.9759C14.5058 16.646 14.067 17.4814 13.833 18.344L14.2973 18.2786L16.8898 17.851L17.09 17.6464C18.2432 16.3799 20.1931 16.2095 21.5246 17.2871L21.9613 17.3098Z"
           fill="#EA4335"
         />
         <path
           d="M25.1042 18.3059C24.8063 17.2087 24.1945 16.2222 23.344 15.4677L21.5246 17.2871C21.9038 17.5969 22.2076 17.9888 22.4133 18.4331C22.6189 18.8775 22.721 19.3628 22.7118 19.8523V20.1753C23.6059 20.1753 24.331 20.9002 24.331 21.7945C24.331 22.6887 23.606 23.3955 22.7118 23.3955H19.4688L19.1504 23.7412V25.6833L19.4688 25.988H22.7117C25.0377 26.0062 26.9381 24.1534 26.9562 21.8274C26.9616 21.1333 26.7954 20.4485 26.4723 19.8342C26.1492 19.2198 25.6792 18.6948 25.1042 18.3059Z"
           fill="#4285F4"
         />
         <path
           d="M16.2303 25.9881H19.4687V23.3955H16.2303C16.001 23.3954 15.7745 23.3458 15.5663 23.25L15.1068 23.391L13.8015 24.6873L13.6877 25.1285C14.4198 25.6812 15.313 25.9921 16.2303 25.9881Z"
           fill="#34A853"
         />
         <path
           d="M16.2303 17.5782C13.9043 17.592 12.0299 19.4889 12.0438 21.815C12.0476 22.456 12.1977 23.0876 12.4826 23.6618C12.7675 24.236 13.1797 24.7376 13.6878 25.1284L15.5663 23.25C14.7514 22.8817 14.3891 21.9227 14.7574 21.1077C15.1256 20.2927 16.0847 19.9305 16.8996 20.2987C17.2587 20.461 17.5463 20.7486 17.7085 21.1077L19.5871 19.2292C19.1928 18.7137 18.6846 18.2965 18.1023 18.0101C17.52 17.7237 16.8793 17.5758 16.2303 17.5782Z"
           fill="#FBBC05"
         />
       </g>
       <defs>
         <clipPath id="clip0_3012_1182">
           <rect
             width="15"
             height="12"
             fill="white"
             transform="translate(12 14)"
           />
         </clipPath>
       </defs>
     </svg>
    }
    href="https://doc.suger.io/integrations/lago"
  >
    Quickly list, transact, and co-sell on GCP Marketplace with Lago, via
    Suger.io integration.
  </Card>
</CardGroup>


# Adyen

Lago's native integration with Adyen allows you to collect payments automatically when new invoices are generated.

Lago's seamless integration with Adyen offers a wide range of payment options, enabling you to conveniently collect payments from your customers. Supported payment methods include:

*   Card payments (Visa, MasterCard, CB)
*   Apple Pay
*   Paypal
*   American Express
*   Amazon Pay
*   Google Pay

And many more! With Lago's native Adyen integration, you can offer your customers a variety of payment options, enhancing their convenience and flexibility during transactions.

<Warning>
  Please ensure that you have added payment methods to your Adyen account before setting up the integration ([see Adyen documentation](https://docs.adyen.com/payment-methods/add-payment-methods/)).
</Warning>

## Connecting Lago to Adyen

To set up the Adyen integration in Lago from our user interface, follow these steps:

1.  In the side menu of your Lago app, navigate to **Settings**;
2.  Select the **Integrations** tab;
3.  Click **"Adyen"** to create a connection;
4.  Give a name to this connection;
5.  Assign a code for easy identification;
6.  Enter the required connection fields (described in the next section); and
7.  Click **Connect to Adyen** to confirm the integration.

## Adyen Connection Fields

When connecting Lago to Adyen, you need to provide information for the following fields.

<AccordionGroup>
  <Accordion title="1. API Key (mandatory)">
    The API Key is a mandatory field and can be found in your Adyen account. Follow these steps to retrieve the API Key:

    *   Go to your Adyen account and navigate to **Developers** > **API Credentials**;
    *   On the API Credentials page, create new credentials with a type of **Web service user**;
    *   Click on the **Create credentials** button to generate the API Key; and
    *   Copy the API Key and paste it in the corresponding field in Lago. Remember to save the changes.
  </Accordion>

  <Accordion title="2. Merchant Account (mandatory)">
    The Merchant Account is required to ensure that Lago targets the correct Adyen account. To find the Merchant Account:

    *   Go to **Settings** > **Merchant accounts** in your Adyen account; and
    *   Copy the **Account code** of the targeted account you want to use with Lago.
  </Accordion>

  <Accordion title="3. Live Prefix (optional)">
    The Live Prefix represents the prefix url of your live Adyen account. This field is optional. If left empty, you can connect a test account. However, for live accounts, you must provide a Live Prefix. Follow these steps to obtain the Live Prefix:

    *   Go to **Developers** > **API URLs** > **Prefix** in your Adyen account.
  </Accordion>

  <Accordion title="4. HMAC Signature (optional)">
    Adyen's HMAC signatures are used to protect webhook endpoints and messages created by Adyen. Lago requires this signature to properly decrypt outgoing webhooks from Adyen. To find the HMAC Signature:

    *   Create or edit a webhook in Adyen by accessing **Developers** > **Webhooks**;
    *   Choose a webhook, e.g. Standard webhook; and
    *   Under "Security" settings, you can find the HMAC Key.

    <Tip>
      The Live Prefix and HMAC Signature fields are optional and may not be required depending on your use case.
    </Tip>
  </Accordion>
</AccordionGroup>

## Setting up Adyen's payments auto-capture

To enable automatic payment capture in your Adyen account, ensure that you have configured the account settings accordingly. Automatic payment capture allows for immediate processing without manual intervention. Refer to Adyen's documentation for instructions on [setting up auto capture](https://docs.adyen.com/online-payments/capture#automatic-capture).

## Turn on Adyen's recurring details

In Adyen, to enable recurring payments for a stored payment method, follow these steps:

1.  Go to Developers > Additional Data;
2.  Check the box for Recurring Details; and
3.  Click Save.

<Frame caption="Adyen recurring details option">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/adyen-recurring-options.png" />
</Frame>

## Setting up Adyen Webhook for listening to important events

**This step is crucial and mandatory** for Lago to receive and process messages from Adyen, enabling functionalities such as customer creation/update, payment processing, and refunds. To configure Adyen webhook and establish communication with Lago, follow the steps below:

1.  Access your Adyen application and navigate to the **Developers** section;
2.  Select **Webhooks** and create a new webhook of type **Standard**;
3.  In the **Server configuration** section, locate the **General** settings; and
4.  Copy and paste the following URL: **`https://api.getlago.com/webhooks/adyen/{{your_organization_id}}?code={{connection_code}}`**.

<Tip>
  You can find your Organization ID in Lago under the Developers section in Lago, specifically in **API keys & ID** > **Organization ID**.
</Tip>

<Tip>
  To find your **connection code**, navigate to the Integrations section in Lago and select the appropriate connection code for your Adyen integration.
</Tip>

**Please ensure that you complete this setup correctly, as your Adyen integration will not function without this vital step.**

## Setting Adyen as a Payment Provider for a customer

In order to facilitate automated payment collection, it is essential for the customer to exist in both the Lago and Adyen databases. Please note that in Adyen, customers are referred to as **Shoppers**.

### Adding a new customer in Adyen

If the customer does not already exist in Adyen, you can create them in Lago using either the user interface or the **[API](/api-reference/customers/create)**. When providing customer information, please ensure the following:

1.  Set Adyen as the customer's **default payment provider**;
2.  Select the Adyen connected account;
3.  Keep the field associated with the **Adyen Payment Provider Customer ID** empty; and
4.  **Enable** the option to automatically create the customer in Adyen.

<Frame caption="Adyen as PSP for new customer">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/adyen-new-customer.png" />
</Frame>

Once the customer is added in Lago, they will be automatically synchronized with Adyen. Adyen will generate a unique Shopper ID, which will be stored in Lago. Typically, Adyen utilizes the Lago customer's **`external_id`** as the Shopper ID for seamless integration between the two platforms.

Upon successful customer creation, you will receive two **[webhook messages](/api-reference/webhooks/messages)** to keep you informed:

1.  **`customer.checkout_url_generated`**: This message includes the checkout URL that provides access to the default payment method. It allows you to perform a pre-authorization payment and store the payment method securely; and
2.  **`customer.payment_provider_created`**: This message confirms the successful creation of the customer in Adyen, indicating that the customer's details have been added to the Adyen database.

<Warning>
  You may need to enable Developers -> Additional Data -> Payment -> Recurring details for the customer to be automatically created.
</Warning>

<Warning>
  Please note that the customer will be created in Adyen only if the payment method has been stored through the checkout URL and pre-authorization payment.
</Warning>

### Using an existing customer from Adyen

If the customer and direct debit mandate already exist in Adyen, you can create the customer record in Lago using either the user interface or **[the API](/api-reference/customers/create)**. Follow these steps when adding customer information:

1.  Set Adyen as the **default payment provider** for the customer in Lago;
2.  Select the Adyen connected account;
3.  Provide the **Adyen [Shopper Reference](https://docs.adyen.com/point-of-sale/card-acquisition/identifiers#:~:text=Shopper%20reference%3A%20a,contract%20payments.)** as the Lago **Payment provider customer ID**.
4.  **Disable** the option to automatically create the customer in Adyen.

By following these steps, you can integrate an existing customer from Adyen into Lago, ensuring synchronization and consistency between the two platforms.

<Frame caption="Adyen as PSP for existing customer">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/adyen-migration.png" />
</Frame>

## Redirect url after checkout[](#checkout-redirect-url "Direct link to heading")

After establishing the connection with Adyen, set a success URL where your end customer will be directed after completing the checkout.
Please note that if it's not defined, your end customer will be redirected to Adyen's website.

Please note that you can edit or delete the redirect URL, and this will only affect new checkout URLs created.

<Warning>
  URL defined should always begin with `http://` or `https://`.
</Warning>

## Adyen Checkout: storing customer's payment method information

When Lago automatically creates a customer in Adyen, you will receive a checkout link from Lago to facilitate the storage of your customer's payment method information.

The payload sent by Lago will have the following structure, with the checkout link stored under **`checkout_url`**:

```json
{
  "webhook_type": "customer.checkout_url_generated",
  "object_type": "payment_provider_customer_checkout_url",
  "payment_provider_customer_checkout_url": {
    "lago_customer_id": "88d23508-47fd-46bb-a87e-50c50f3cb371",
    "external_customer_id": "hooli_1234",
    "payment_provider": "adyen",
    "payment_provider_code": "adyen_test",
    "checkout_url": "https://test.adyen.link/PLEEA656869B11DF6B"
  }
}
```

<Info>
  Note: The checkout link automatically expires after 69 days.
</Info>

By utilizing this provided checkout link, your customers can perform a pre-authorization payment. It's important to note that the pre-authorization payment will not collect any funds from the customer. Once the pre-authorization is confirmed, Lago will send the payment method details and securely store them into Adyen for future transactions.

<Frame caption="Adyen checkout with Lago">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/adyen-checkout.png" />
</Frame>

## Regenerate checkout link on demand

In cases where your end customer has not had the opportunity to complete the checkout process to inform their payment method
or wishes to modify the saved payment information, you can generate a new checkout link using the designated [endpoint](/api-reference/customers/psp-checkout-url).

```json
POST /api/v1/customers/:customer_external_id/checkout_url
```

Upon successful generation, the new checkout link will be available in the endpoint response, and it will not be delivered through a webhook message.
It is important to note that the new link will inherit the same expiration setting as the original one.

It is crucial to be aware that if a customer is not associated with any payment provider, the response will contain an error message.

## Creating payments from Lago Invoices

When a customer has Adyen defined as their payment provider, Lago seamlessly automates the process of triggering payments in Adyen whenever a new invoice is generated.

This integration ensures that payments are initiated in Adyen without any manual intervention. Lago's automatic payment creation saves time and effort, providing a streamlined experience for both you and your customers.

## Creating refunds from Lago Credit Notes

In cases where a customer has Adyen defined as their payment provider, Lago simplifies the refund process by automatically triggering refunds in Adyen whenever a new refund is initiated through credit notes.

This integration eliminates the need for manual refund processing and ensures that refunds are efficiently handled in Adyen. Lago's automated refund functionality helps you maintain accurate and timely refund transactions, enhancing customer satisfaction and operational efficiency.

## Payment disputes

In the event of a **lost** chargeback (dispute) within Adyen, Lago initiates an automatic response by marking the relevant invoice as disputed lost. This action involves populating the `dispute_lost_at` field with the timestamp when the dispute was lost. Following this update:

*   The invoice becomes non-voidable;
*   Generating a credit note is possible; however, refunding the payment back to the original payment method is not permitted; and
*   The invoice cannot be resent for collection.

## Watch the demo video

<iframe width="100%" height="400" src="https://www.youtube.com/embed/Zh7NNbgS7Bo" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />


# GoCardless

Lago's native integration with GoCardless allows you to collect payments via direct debit.

## Integration setup[](#integration-setup "Direct link to heading")

### Connect your GoCardless account[](#connect-your-gocardless-account "Direct link to heading")

To connect to GoCardless through the user interface:

1.  In the side menu, select **"Settings"**;
2.  Open the **"Integrations"** tab;
3.  Click **"GoCardless"** to create a connection;
4.  Give a name to this connection;
5.  Assign a code for easy identification;
6.  Click on **"Connect to GoCardless"** to be redirected to the GoCardless application;
7.  Create a GoCardless account or log in to your existing account; and
8.  Connect your account to be redirected to the Lago application.

When the OAuth connection is active, you will see the screen below, with your
secret key.

<Frame caption="Active OAuth connection with GoCardless">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/gcl-oauth-65c0e5a1a2767f606b55395e0ba394e4.png" />
</Frame>

### Create webhook endpoints[](#create-webhook-endpoints "Direct link to heading")

<Tip>
  To complete this process, you will need:

  *   Your Lago **organization ID**, available in the **"API keys & ID"** tab of the
      **"Developers"** section; and
  *   Your **secret key**, available in the **"Integrations"** tab of the
      **"Settings"** section ([learn more](#connect-your-gocardless-account)).
</Tip>

If you want Lago to automatically retrieve the status of the payments processed
via GoCardless, you must create a webhook endpoint in GoCardless. To do so:

1.  Log in to your [GoCardless account](https://manage.gocardless.com/sign-in);
2.  Go to the **"Developers"** section;
3.  In the upper right corner, click **"Create"** and then select **"Webhook
    endpoint"**;
4.  Choose a name for this webhook (e.g. Lago);
5.  Enter the following URL: `https://api.getlago.com/webhooks/gocardless/{{organization_id}}?code={{connection_code}}` (you must replace `organization_id` with your Lago organization ID, and the `connection_code` by the targeted Lago connection);
6.  Enter your secret key; and
7.  Click **"Create webhook endpoint"**.

<Frame caption="Webhook endpoint creation in GoCardless">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/gcl-webhook-9e1e96b038542112b1609ebb70a9dda9.png" />
</Frame>

In addition to this, you must create a webhook endpoint in Lago to retrieve the
checkout URL associated with each customer account
([learn more](#direct-debit)). To do so:

1.  Go to the **"Developers"** section of the Lago application;
2.  In the **"Webhooks"** tab, click **"Add a webhook"** on the right;
3.  Enter your webhook URL; and
4.  Click **"Add webhook"** to confirm.

For more information about our webhooks, please refer to the
[API documentation](/api-reference/webhooks/format---signature).

## Redirect url after checkout[](#checkout-redirect-url "Direct link to heading")

After establishing the connection with GoCardless, set a success URL where your end customer will be directed after completing the checkout.
Please note that if it's not defined, your end customer will be redirected to GoCardless’s website.

Please note that you can edit or delete the redirect URL, and this will only affect new checkout URLs created.

<Warning>
  URL defined should always begin with `http://` or `https://`.
</Warning>

## Customer information[](#customer-information "Direct link to heading")

To collect payments automatically, the customer must exist in both the Lago and
GoCardless databases.

### New customer[](#new-customer "Direct link to heading")

If the customer does not already exist in GoCardless, you can first create them
in Lago, either via the user interface or
[the API](/api-reference/customers/create). When adding customer information, you
must:

1.  Provide the customer's email address;
2.  Define GoCardless as the **default payment provider**;
3.  Select the GoCardless connected account;
4.  Leave the field associated with the **GoCardless customer ID** blank; and
5.  **Enable** the option to automatically create the customer in GoCardless.

The customer will automatically be added to GoCardless. GoCardless will then
return the customer ID, which will be stored in Lago.

<Frame caption="Creation of a new customer with GoCardless">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/gcl-customer-new-3f7f52c1614edb8b577b075e35de99fb.png" />
</Frame>

When the customer is successfully created, you will receive two
[webhook messages](/api-reference/webhooks/messages):

*   `customer.payment_provider_created` that confirms the creation of the customer
    in GoCardless; and
*   `customer.checkout_url_generated` that includes the checkout URL to set up the
    direct debit ([learn more](#direct-debit)).

### Existing customer[](#existing-customer "Direct link to heading")

If the customer and direct debit mandate already exist in GoCardless, then you
should create the customer record in Lago, either via the user interface or
[the API](/api-reference/customers/create). When adding customer information, you
must:

1.  Provide the customer's email address;
2.  Define GoCardless as the **default payment provider**;
3.  Select the GoCardless connected account;
4.  Provide the **GoCardless customer ID**; and
5.  **Disable** the option to automatically create the customer in GoCardless.

<Frame caption="Migration of an existing GoCardless customer">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/gcl-customer-migration-959faab7b09d8c09866b477845ad8b3b.png" />
</Frame>

## Direct debit[](#direct-debit "Direct link to heading")

To collect payments via direct debit, a mandate must be created. To do so:

1.  Retrieve the checkout URL included in the `customer.checkout_url_generated`
    webhook; and
2.  Redirect your customer to the checkout page, so that they can complete the
    online form and approve the mandate.

The mandate must be validated by GoCardless before the first payment can be
processed. It can take up to six business days to validate a new mandate. For
more information about payment timings, please consult the
[GoCardless FAQ](https://gocardless.com/faq/merchants/direct-debit/).

<Warning>
  To collect payments via direct debit, the currency of the mandate must match
  the currency of the plan associated with the customer's subscription.
</Warning>

<Frame caption="Direct debit setup with GoCardless">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/gcl-mandate-c4e336d031a583d002189188ab2599e2.png" />
</Frame>

Each time a new invoice with an **amount greater than zero** is generated by
Lago, a payment will automatically be created. GoCardless will record the
invoice ID and process the payment. Payments via direct debit are usually
processed within five business days. If the payment is successful, the status of
the payment will switch from `pending` to `succeeded`.

If the payment fails, the status of the payment will switch from `pending` to
`failed` and Lago will generate an `invoice.payment_failure`
[webhook](/api-reference/webhooks/messages).

<Tip>
  If you have signed up for [GoCardless
  Success+](https://gocardless.com/solutions/success-plus/), failed payments may
  be automatically resubmitted, in which case Lago will automatically update the
  invoice payment status.
</Tip>

## Regenerate checkout link on demand

In cases where your end customer has not had the opportunity to complete the checkout process to inform their payment method
or wishes to modify the saved payment information, you can generate a new checkout link using the designated [endpoint](/api-reference/customers/psp-checkout-url).

```json
POST /api/v1/customers/:customer_external_id/checkout_url
```

Upon successful generation, the new checkout link will be available in the endpoint response, and it will not be delivered through a webhook message.
It is important to note that the new link will inherit the same expiration setting as the original one.

It is crucial to be aware that if a customer is not associated with any payment provider, the response will contain an error message.


# Stripe

Lago's native integration with Stripe allows you to collect payments automatically when new invoices are generated.

## Watch the demo video

<iframe width="100%" height="400" src="https://www.youtube.com/embed/NH8MCMaHeFM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />

## Integration setup[](#integration-setup "Direct link to heading")

To set up the integration with Stripe through the user interface:

1.  In the side menu, select **"Settings"**;
2.  Select the **"Integrations"** tab;
3.  Click **"Stripe"** and add a new connection;
4.  Give this new connection a name and a code;
5.  Enter your Stripe API key ([locate your API key](https://support.stripe.com/questions/locate-api-keys-in-the-dashboard)); and
6.  Click **"Connect to Stripe"** to confirm.

<Info>
  By default, customers created in Lago are not automatically created in Stripe.
  If you want your Lago customers to be added to Stripe, you need to activate
  this option ([learn more](#new-customer)).
</Info>

## Redirect url after checkout[](#checkout-redirect-url "Direct link to heading")

After establishing the connection with Stripe, set a success URL where your end customer will be directed after completing the checkout.
Please note that if it's not defined, your end customer will be redirected to Stripe's website.

Please note that you can edit or delete the redirect URL, and this will only affect new checkout URLs created.

<Warning>
  URL defined should always begin with `http://` or `https://`.
</Warning>

## Customer information[](#customer-information "Direct link to heading")

To collect payments automatically, the customer must exist in both the Lago and
Stripe databases.

### New customer[](#new-customer "Direct link to heading")

If the customer does not already exist in Stripe, you can first create them in
Lago, either via the user interface or [the API](/api-reference/customers/create).
When adding customer information, you must:

1.  Define Stripe as the **default payment provider**;
2.  Leave the field associated with the **Stripe customer ID** blank;
3.  **Enable** the option to automatically create the customer in Stripe; and
4.  Define payment method options for this customer. Possible values are `card`, `link`, `sepa_debit`, `us_bank_account` and `bacs_debit`.

The customer will automatically be added to Stripe. Stripe will then return the
customer ID, which will be stored in Lago.

<Frame caption="Creation of a new customer with Stripe">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/stripe-customer-new.png" />
</Frame>

### Existing customer[](#existing-customer "Direct link to heading")

If the customer already exists in Stripe but not in Lago, you should create the
customer record, either via the user interface or
[the API](/api-reference/customers/create). When adding customer
information, you must:

1.  Define Stripe as the **default payment provider**;
2.  Provide the **Stripe customer ID**;
3.  **Disable** the option to automatically create the customer in Stripe; and
4.  Define payment method options for this customer. Possible values are `card`, `link`, `sepa_debit`, `us_bank_account` and `bacs_debit`.

<Frame caption="Migration of an existing Stripe customer">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/guide/payments/images/stripe-customer-migration.png" />
</Frame>

## Supported payment methods

Lago's Stripe integration accommodates a variety of payment methods, both generic and region-specific.
The checkout URL provided by Lago is designed to handle multiple payment options seamlessly.

<AccordionGroup>
  <Accordion title="Card payments" icon="credit-card">
    Lago's Stripe integration includes a universal card payment method that supports various currencies, ideal for global transactions.
    This method is set as the default to facilitate recurring payments, ensuring Lago can process charges for your customers efficiently.

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

    curl --location --request POST "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "customer": {
          "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "address_line1": "5230 Penfield Ave",
          "billing_configuration": {
            "invoice_grace_period": 3,
            "payment_provider": "stripe",
            "provider_customer_id": "cus_12345",
            "sync": true,
            "sync_with_provider": true,
            "provider_payment_methods": ["card"]
          }
        }
      }'
    ```
  </Accordion>

  <Accordion title="SEPA debits (EU only)" icon="money-bill-transfer">
    For European customers, Lago supports Stripe SEPA Debit (Single Euro Payments Area).
    Accepting a mandate through this method authorizes you to debit your customers' accounts for recurring payments via Lago.
    The designated payment method for SEPA transactions within Lago is identified as `sepa_debit`.
    It's important to note that **this payment option is exclusive to invoices in `EUR` currency**.

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

    curl --location --request POST "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "customer": {
          "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "address_line1": "5230 Penfield Ave",
          "billing_configuration": {
            "invoice_grace_period": 3,
            "payment_provider": "stripe",
            "provider_customer_id": "cus_12345",
            "sync": true,
            "sync_with_provider": true,
            "provider_payment_methods": ["sepa_debit"]
          }
        }
      }'
    ```
  </Accordion>

  <Accordion title="ACH debits (US only)" icon="flag-usa">
    For US-based transactions, Lago integrates Stripe ACH Debit, leveraging the Automated Clearing House for electronic bank-to-bank payments.
    Upon accepting a mandate, you gain authorization to execute recurring debits from your customers' accounts through Lago.
    The designated payment method for ACH transactions within Lago is identified as `us_bank_account`.
    It's important to note that **this payment option is exclusive to invoices in `USD` currency**.

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

    curl --location --request POST "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "customer": {
          "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "address_line1": "5230 Penfield Ave",
          "billing_configuration": {
            "invoice_grace_period": 3,
            "payment_provider": "stripe",
            "provider_customer_id": "cus_12345",
            "sync": true,
            "sync_with_provider": true,
            "provider_payment_methods": ["us_bank_account"]
          }
        }
      }'
    ```
  </Accordion>

  <Accordion title="BACS debits (UK only)" icon="credit-card-front">
    For UK transactions, Lago integrates Stripe BACS Debit, utilizing the UK's BACS system for direct bank-to-bank payments.
    By accepting a mandate with this method, you're authorized to initiate recurring debits from your customers' accounts through Lago.
    The specific payment method for BACS transactions within Lago is designated as `bacs_debit`.
    It's important to note that **this payment method is exclusively for invoices in `GBP` currency.**

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

    curl --location --request POST "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "customer": {
          "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "address_line1": "5230 Penfield Ave",
          "billing_configuration": {
            "invoice_grace_period": 3,
            "payment_provider": "stripe",
            "provider_customer_id": "cus_12345",
            "sync": true,
            "sync_with_provider": true,
            "provider_payment_methods": ["bacs_debit"]
          }
        }
      }'
    ```
  </Accordion>

  <Accordion title="Link" icon="link">
    For card transactions, you can enable the [Link](https://stripe.com/payments/link) feature to offer one-click payments.
    Link automatically fills in your customers' payment information, ensuring a seamless and secure checkout experience.

    <Warning>
      If you are using the `link` feature, it must be used in conjunction with `card`.
    </Warning>

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

    curl --location --request POST "$LAGO_URL/api/v1/customers" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "customer": {
          "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
          "address_line1": "5230 Penfield Ave",
          "billing_configuration": {
            "invoice_grace_period": 3,
            "payment_provider": "stripe",
            "provider_customer_id": "cus_12345",
            "sync": true,
            "sync_with_provider": true,
            "provider_payment_methods": ["card", "link"]
          }
        }
      }'
    ```
  </Accordion>
</AccordionGroup>

## Stripe Checkout: storing customer's payment method information

<Info>
  Checkout page shows only selected payment methods for customers.
</Info>

When Lago automatically creates a customer in Stripe, you will receive a checkout link from Lago to facilitate the storage of your customer's payment method information.

The payload sent by Lago will have the following structure, with the checkout link stored under `checkout_url`:

```json
{
  "webhook_type": "customer.checkout_url_generated",
  "object_type": "payment_provider_customer_checkout_url",
  "payment_provider_customer_checkout_url": {
    "lago_customer_id": "88d23508-47fd-46bb-a87e-50c50f3cb371",
    "external_customer_id": "hooli_1234",
    "payment_provider": "stripe",
    "checkout_url": "https://checkout.stripe.com/c/pay/prod_c15sTbBMLep5FKOA9b9pZBiRBBYYSU1IJ5T89I5TTtpKgzE380JSmxnVYz#fidkdWxOYHw"
  }
}
```

<Warning>
  Note: The checkout link automatically expires after 24 hours!
</Warning>

By utilizing this provided checkout link, your customers can perform a pre-authorization payment. It's important to note that the pre-authorization payment will not collect any funds from the customer. Once the pre-authorization is confirmed, Lago will send the payment method details and securely store them into Stripe for future transactions.

## Regenerate checkout link on demand

In cases where your end customer has not had the opportunity to complete the checkout process to inform their payment method
or wishes to modify the saved payment information, you can generate a new checkout link using the designated [endpoint](/api-reference/customers/psp-checkout-url).

```bash
POST /api/v1/customers/:customer_external_id/checkout_url
```

Upon successful generation, the new checkout link will be available in the endpoint response, and it will not be delivered through a webhook message.
It is important to note that the new link will inherit the same expiration setting as the original one.

It is crucial to be aware that if a customer is not associated with any payment provider, the response will contain an error message.

## Default payment method

When you add a new payment method in Stripe, **Lago automatically sets it as the default**.
This guarantees that Lago uses the latest payment method for a customer. However, if you manually designate one of
multiple payment methods as the default, Lago will use it for payments instead the most recent one.

## Payment intents[](#payment-intents "Direct link to heading")

Once Stripe is connected and the customer exists in both databases, you can
start collecting payments.

### Succeeded payments

Each time a new invoice with an **amount greater than zero** is generated by
Lago, a payment intent will automatically be created. Stripe will record the
invoice ID and process the payment. If the payment is successful, the status of
the payment will switch from `pending` to `succeeded`.

### Failed payments

If the payment fails, the status of the payment will switch from `pending` to
`failed` and Lago will generate an `invoice.payment_failure`
[webhook](/api-reference/webhooks/messages).

### Payments requiring validation

When a payment requires multi-step authentication, such as 3D Secure (3DS), Lago triggers a `payment.requires_action` [webhook](/api-reference/webhooks/messages#payment-requires-action).
This webhook provides the URL for completing the 3DS process. It's important to note that **most payments in India require 3DS authentication** due to [RBI regulations](https://www.rbi.org.in/Scripts/NotificationUser.aspx?Id=12051\&Mode=0).

### Minimum payment amount

If the new invoice amount falls below the [minimum amount supported by Stripe](https://stripe.com/docs/currencies#minimum-and-maximum-charge-amounts), the payment status will remain as `pending`.

<Warning>
  A valid payment method for the customer must be defined in Stripe for the
  payment intent to succeed ([learn how to save payment
  details](https://stripe.com/docs/payments/save-and-reuse)).
</Warning>

## Payment disputes

In the event of a **lost** payment dispute within Stripe, Lago initiates an automatic response by marking the relevant invoice as disputed lost. This action involves populating the `dispute_lost_at` field with the timestamp when the dispute was lost. Following this update:

*   The invoice becomes non-voidable;
*   Generating a credit note is possible; however, refunding the payment back to the original payment method is not permitted; and
*   The invoice cannot be resent for collection.


# Anrok

Lago's native integration with Anrok allows you to automatically update your invoices with tax amounts sourced directly from Anrok. This integration ensures compliance with international tax regulations by calculating taxes for US & non-US obligations, like VAT.

<Info>
  **PREMIUM FEATURE** ✨

  This feature is only available to users with a premium license. Please
  **[contact us](mailto:hello@getlago.com)** to get access to Lago Cloud and Lago
  Self-Hosted Premium.
</Info>

## Overview

Lago’s integration with Anrok simplifies tax calculation and reporting by syncing invoice amounts with Anrok for filing.

When an invoice is in draft status, Lago generates an ephemeral transaction in Anrok to calculate the preliminary taxes. Once the invoice is finalized, Lago creates a permanent transaction in Anrok to calculate the final taxes, marking it for reporting to the appropriate tax authority via Anrok.

To calculate the appropriate tax for each line item, Lago sends the customer’s address, tax identifier (if applicable), and the relevant product ID to Anrok. Anrok then calculates the tax for the invoice and returns the data to Lago, which is used to update the invoice with accurate tax information. Additionally, Lago synchronizes updates for voided and disputed invoices, as well as any credit notes created, ensuring that your records remain up to date.

## Prerequisites

1.  **Premium feature**: To access Anrok via Lago, you’ll need to be under the Premium license.
2.  **Getting Started**: We recommend reviewing the [Anrok Getting Started Guide](https://help-center.anrok.com/hc/en-us/categories/4410165176339-Getting-Started-Guide) before initiating the setup process.
3.  **Anrok Account**: Ensure you have an Anrok account. Ideally, test the connection via an Anrok sandbox account to your Lago test account. Contact the Anrok team to request a free sandbox account.
4.  **Physical Nexus**: Make sure you are correctly recording physical nexus in Anrok. Add or manage your physical nexus through the "Jurisdictions" tab by clicking the “Manage Physical Nexus” button.
5.  **Products in Anrok**: Create products in Anrok, assigning a tax configuration to each product you sell in Lago. You will need the IDs of these products when setting up the Anrok integration in Lago (see the mapping below).
6.  **Customer Exemptions in Anrok**: If necessary, upload valid exemption certificates for your customers in Anrok. Ensure that when you create a customer profile in Lago, you use the same customer ID as in Anrok. This consistency allows Lago to correctly identify the customer and apply the exemption certificates when calculating taxes.

## Connect Anrok to Lago

Lago allows you to connect your different Anrok instances. For example, you could connect both a sandbox and a production Anrok account. To do so:

1.  In Lago, please go to Settings > Integration
2.  Click on Anrok
3.  Define a name and code for this connection; and
4.  Enter your Anrok API key

<Frame caption="Connect Anrok to Lago">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/anrok-connection.png" />
</Frame>

### Mapping items between Lago and Anrok (mandatory)

To synchronize invoices and retrieve tax data, Lago needs to establish a one-to-one relationship between its objects and Anrok products. Follow these steps to map an item:

1.  In Anrok, navigate to the **Products IDs** section.
2.  Click on a product and **copy its Product ID.**
3.  In Lago, navigate to **Integration** > **Anrok** > **Mapping**.
4.  Choose the item you want to associate with the Product ID selected in step 2.
5.  **Paste the Product ID to map the item** — repeat this action for all items in Lago that require mapping.

<Info>
  The invoice will be marked as `failed` if any item requiring tax calculation from Anrok is not properly mapped and no fallback item is provided.
</Info>

### Mapping a fallback item (mandatory)

The fallback item serves as a backup and is used if the mapping of other items is not defined. This dummy item ensures continuous data synchronization between Lago and Anrok in the event of mapping issues.

<Frame caption="Mapping Lago item to Anrok">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/anrok-mapping.png" />
</Frame>

## Customer configuration for tax calculation

### Customer synchronization

When creating or updating a Lago customer, you can choose to link it to an existing Anrok customer.

The first option is to **automatically create a new customer from Lago to Anrok**. Follow these steps:

1.  Create or update a new Lago customer;
2.  Select the targeted Anrok connection;
3.  Check the box labeled ‘Create this customer automatically in Anrok’; and
4.  Save and create this new customer.

If the customer is successfully created in Anrok, a new field will be displayed in the Lago customer view, providing a direct link to the corresponding Anrok customer.

<Frame caption="Create customer in Anrok">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/anrok-create-customer.png" />
</Frame>

The second option is to **import an existing Anrok customer to a Lago customer**. Follow these steps:

1.  Create or update a Lago customer;
2.  Select the targeted Anrok connection;
3.  Ensure the box labeled ‘Create this customer automatically in NetSuite’ is unchecked;
4.  Paste the Anrok customer ID in the appropriate field; and
5.  Save and create this new customer.

If the customer is successfully synced in Anrok, a new field will be displayed in the Lago customer view, providing a direct link to the corresponding Anrok customer.

<Frame caption="Sync Anrok customer in Lago">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/anrok-sync-customer.png" />
</Frame>

<Info>
  Please note that in both cases, the customer will be created in Anrok after the first invoice is synchronized.​
</Info>

### Address requirements

Anrok requires that each customer in Lago has a valid shipping address. If a shipping address is not available, Lago will default to using the billing address for tax calculation purposes. If both addresses are invalid or missing, Lago will be unable to generate the invoice, and the invoice status will be marked as failed. In such cases, you will be notified of the failure in the dashboard and via webhook.

<Frame caption="Mapping Lago item to Anrok">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/anrok-failed-invoice.png" />
</Frame>

### Tax identifier

If a customer has a `tax_identification_number` configured in Lago, this ID will be sent to Anrok for tax calculation and reporting. This ID is essential for determining whether the transaction is subject to a reverse charge in eligible VAT countries.

### Tax exempt customers

For customers who qualify for tax exemptions, you need to create a Certificate in your Anrok dashboard. Ensure that the customer profile in Lago uses the same customer ID as in Anrok in the Anrok customer ID. This consistency allows Lago to correctly identify the customer and apply the exemption certificates when calculating taxes.

## Current usage

Lago queries Anrok for the current usage and wallet ongoing balance. To ensure the best experience, Lago caches the results of current usage taxes for 24 hours.

## Error management

### Refresh draft invoice with tax errors

When an invoice is in `draft` and encounters a tax synchronization error, you have the option to refresh the invoice to recalculate the tax. The invoice remains editable during this process, and the error will not prevent the invoice from being `finalized`. However, if the error persists after attempting to finalize the invoice, the invoice will be marked as `failed`.

### Retry synchronization for failed invoice

When an invoice fails due to a tax synchronization error, you have the option to manually re-sync each invoice individually from the invoice details page or via this [endpoint](/api-reference/invoices/retry_finalization). Alternatively, you can go to the integration settings and trigger a bulk invoice synchronization.

<Frame caption="Mapping Lago item to Anrok">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/anrok-sync-all-invoices.png" />
</Frame>

### Retry synchronization for voided / disputed invoices

When an invoice is voided or disputed, Lago will sync this updated record with Anrok to ensure your reports are accurate. If the sync fails, you will be notified via webhook. In that case, please manually resync the voided or disputed invoice through the dashboard.

### Retry synchronization for credit notes

When a credit note is created, Lago will sync this record with Anrok to ensure your reports are accurate. If the sync fails, you will be notified via webhook. In that case, please manually resync the credit note through the dashboard.

### Pay in advance non invoiceable charge

Lago will notify you via webhook if a tax error occurs when a non-invoiceable fee paid in advance is generated. The fee will not be created. Please note that you will need to fix the issue and resend the event to generate the fee. For any assistance, please contact the Lago team.

### Tax error scenario

If Lago is unable to generate an invoice or sync it to Anrok, you will be alerted via the dashboard and webhook.
Tax synchronization and invoice generation can fail due to the following reasons:

1.  Incorrect connection settings (API key).
2.  Items used in objects or fallback items not mapped.
3.  Missing customer shipping or billing address.
4.  Timeout or internal service error.

Tax synchronization can fail during the following processes:

1.  Calculating taxes in one-off-invoice form
2.  Refreshing a draft invoice
3.  Finalizing an invoice
4.  Generating a fee paid in advance non-invoiceable
5.  Fetching current usage
6.  Voiding an invoice
7.  Disputing an invoice
8.  Creating a credit note

If an issue arises, please check the mapping, verify the customer address and launch a synchronization; or contact the Lago team for assistance.


# Lago EU Taxes



Lago now features an automatic European tax detection integration for your customers.

## Enable Lago's EU Tax integration

Activate Lago's automatic EU tax detection in just a few steps:

1.  Navigate to your Lago instance **Settings**;
2.  Select the **'Lago EU Tax Management'** integration;
3.  Enter or confirm your organization's country; and
4.  Hit **'Connect'** to activate this integration.

## Automated EU tax rates detection

When you connect the Lago EU Tax Management integration, it automatically generates a list of standard European tax rates.
These rates, labeled as `automated` in Lago, are synchronized with the latest standard tax rates for European countries,
ensuring your tax calculations are always up-to-date and compliant.

Each tax rate begins with the `lago_` prefix, ensuring a uniform and easily identifiable format across your tax rate list.
This systematic approach simplifies the management and recognition of these automated tax entries within your system.

<Frame caption="Automated tax rates">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/automated-tax-rates.png" />
</Frame>

## Auto-application of taxes: decision tree

<Frame caption="Automated tax rates">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/images/lago-eu-taxes-decision-tree.jpg" />
</Frame>

Lago's initial step in the automated tax application involves verifying if a customer has a `tax_identification_number`.
This check occurs whenever a customer's profile is created or updated, ensuring that the most current tax-related information
is used in subsequent processes.

### B2B tax decision process

When a `tax_identification_number` is identified on a customer profile, Lago conducts a real-time verification
using the [EU's VAT Information Exchange System (VIES)](https://ec.europa.eu/taxation_customs/vies/#/vat-validation) to
confirm the existence of the company.

**In case the VIES check matches a valid company:**

1.  If the customer's company is registered in the same country as your organization, Lago applies the customer
    country's tax rate;
2.  If the customer's company is registered in the same country as your organization, but there is a tax exception for a particular zipcode, Lago applies the tax exception of this specific zipcode; or
3.  If the customer's company is registered in a different country than your organization, Lago implements a
    **reverse charge** mechanism, applying a 0% tax rate.

### B2C tax decision process

If the VIES check does not confirm an active company or if no `tax_identification_number` is provided,
Lago then assesses the `country` associated with your customer. Based on this:

1.  If your customer's `country` is unspecified, Lago defaults to applying your organization's country tax rate; or
2.  If your customer's `country` is within the European Union, Lago applies the tax rate corresponding your customer's EU country; or
3.  If your customer's `country` is outside the European Union, Lago applies a **tax exempt** rate at 0%.

## Guidelines for VIES checks by Lago

Lago performs VIES verifications under these circumstances:

*   The Lago EU Tax Management integration is activated;
*   A customer profile is either created or updated. Changes in customer details could influence their applicable tax rates;
*   Zipcodes are important to define tax exceptions. Make sure to define them for all your customers; and
*   When a new tax rate is identified for a customer, Lago automatically updates the customer's profile by replacing the old tax rate with the new one.

## Logging VIES verifications

Lago ensures transparency and compliance by logging each VIES check. This occurs whenever you create or update a customer.
For each check, Lago dispatches a webhook message. This allows you to record these validations for compliance purposes.
You can access and review any of these automated checks as needed.


# Hightouch

Hightouch is a Data Activation platform that syncs data from sources (database, warehouses, spreadsheet and much more) to business  applications and developer tools. This data can be sent to Lago, our usage-based billing platform, to automate your billing process  and ensure accurate invoicing for your customers.

Here's a step-by-step guide to help you get started:

## Prerequisites

**In Lago:**

1.  Create a Lago organization to manage your billing and invoicing;
2.  Create a Billable metric to track the usage of your customers;
3.  Create a Plan and price the above billable metric to determine the billing rates for your customers; and
4.  Create a Customer and assign the Plan.

**In Hightouch:**

1.  Create a Hightouch account;
2.  Create a data source (ideally, product usage of your customer);
3.  Create a **HTTP Request** destination.

## Send usage from Hightouch to Lago

### Create a data source

To accomplish this, you'll need first to create a source in Hightouch. This can be done by following these simple steps:

1.  Navigate to the **Sources** tab;
2.  Add a **new source**; and
3.  Choose and set up a data source that is available in Hightouch (it could be a database, a warehouse or a spreadsheet, for instance).

<Frame caption="Hightouch Sources">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/usage/images/hightouch-sources-3aa4046d89ec2208963b3e541408a249.png" />
</Frame>

### Use the HTTP Request destination

Lago uses Hightouch's HTTP Request to ingest usage. Here is how to set it up:

1.  Go to the **Destinations** tab;
2.  Select the **HTTP Request** destination;
3.  Define your **Headers**. Lago requires `Authorization` (secret, used for the API Key) and `Content-Type: application/json` headers; and
4.  Save this newly created destination.

<Frame caption="Hightouch HTTP Request Destination">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/usage/images/hightouch-http-destination-d613e2e5663423ea83712c055d893333.png" />
</Frame>

### Create a Sync

In order to send usage from Hightouch to Lago, you will have to create a new **Sync**. To do so, go in the **Syncs** tab and create a new sync from a source to this HTTP Request destination.

1.  Configure when you want to trigger the event (row added, row deleted, row updated);
2.  Define `POST` as the targeted HTTP Method;
3.  Define the targeted url (for usage events, use `https://api.getlago.com/api/v1/events`);
4.  Send data as `JSON` and use the JSON editor;
5.  Define rate limits, if applicable

### Example of JSON payload

You can define manually the JSON payload that will be sent to Lago. Note that Hightouch supports Liquid template language to insert variables from your source to your JSON payload. These variables are created following this syntax: `"{{ row.variable }}"`, *"variable"* being the column name of your source.

Here is a JSON payload example to send usage events to Lago:

```json
{
  "event": {
    "transaction_id": "{{ row.transactionId }}",
    "external_customer_id": "{{ row.customerId }}",
    "code": "invoice_created",
    "properties": {
      "invoice_id": "{{ row.invoiceId }}"
  }
}
}
```

<Info>
  The `body` structure of the event depends on your use case. Please adapt it if needed (*ie: remove or add properties*).
</Info>

### Test and activate your sync

Note that you can test your sync with a data sample. As a result of this test, you should see data flowing into Lago, in the events list. Once you are ready to go, you can activate this sync, and define the periodic trigger.

<Frame caption="Hightouch Test Sync with Lago">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/usage/images/sync-test-hightouch-34f6e41a10dd05b637841b6f4d1581fa.png" />
</Frame>

## Hightouch to Lago - demo video

If easier, please find a demo video explaining the full setup to send events from Hightouch to Lago.

<iframe width="700" height="500" src="https://www.youtube.com/embed/2NBmQYjrz40" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />


# Segment

Segment is a powerful tool that allows you to track the usage of your customers, providing valuable insights that can help you make  data-driven decisions. This data can be sent to Lago, our usage-based billing platform, to automate your billing process and ensure  accurate invoicing for your customers.

Here's a step-by-step guide to help you get started:

## Prerequisites

**In Lago:**

1.  Create a Lago organization to manage your billing and invoicing;
2.  Create a Billable metric to track the usage of your customers;
3.  Create a Plan and price the above billable metric to determine the billing rates for your customers; and
4.  Create a Customer and assign the Plan.

**In Segment:**

1.  Create a Segment account;
2.  Create a data source (ideally, product usage of your customer);

## Send usage from Segment to Lago

### Create a function

To accomplish this, you'll need to create a custom **Function** in Segment. This can be done by following these simple steps:

1.  Navigate to the **Catalog** in Segment;
2.  Click the **Functions** tab to access the custom Functions feature;
3.  Choose to create your first function and follow the prompts to set it up.

<Frame caption="Segment Functions">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/usage/images/segment-catalog-1a7de549eb06d94a6a8ce92565e957a8.png" />
</Frame>

### Use the Destination function

Make sure to select the **Destination function**, as you want to send data from Segment to Lago.

<Frame caption="Destinations function">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/usage/images/destination-function-segment-6131770a6f0e5b7c8e7bf694ca6339b3.png" />
</Frame>

### Post Request to Lago events

To successfully integrate Lago with Segment, you'll need to replace the pre-written functions in the code editor with the following code. This example function, written by the Lago team, will catch a **Track** event from Segment, define the targeted endpoint (events) in Lago, build the body of the request, and finally post the event.

```javascript
// Running everytime a Track call is made on Segment
async function onTrack(event, settings) {

  // events endpoint to reach
  const endpoint = 'https://api.getlago.com/api/v1/events';

  // body of the event following Lago documentation
    const body = {
      event: {
        transactionId: event.messageId,
        externalCustomerId: event.userId,
        code: event.event,
        properties: {
          invoiceId: event.properties.invoice_id
        }
      }
    };

    // Post event
    const response = await fetch(endpoint, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${settings.api}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(body)
    });

    return response.json();

  }
```

<Info>
  This function can be adapted with Identify, Group or Page events. Please, refer to [Segment's documentation](https://segment.com/docs/connections/functions/destination-functions/) for all available actions.
</Info>

<Info>
  The `body` structure of the event depends on your use case. Please adapt it if needed (*ie: remove or add properties*). You can also add conditions if you want to send data to Lago only on specific events.
</Info>

### Use the test mode editor

By using a sample event, you can preview the incoming data fetched from a Segment event. This will help you post a request for existing data or debug.

<Frame caption="Segment Sample Events">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/usage/images/test-mode-segment-747eee5ec2ff46a349064e3dbbf4a758.png" />
</Frame>

### Hide sensitive data

Let's take back the example from the code written above. We decided to hide the **API Key** and mark it as sensitive information. By setting this as a variable, you make sure not to hard code your private key in the function.

To create **Settings** variables:

1.  Go to the **Settings** tab;
2.  **Add** a new Setting;
3.  Define a **Name** and a **Label** for this Settings;
4.  Define it as **Required** or **Optional**; and
5.  Mark is as **Sensitive** or not.

<Frame caption="Hide sensitive data with settings variables">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/integrations/usage/images/segment-settings-variable-c19b5f3de23eec11ffe475e8272dc5ff.png" />
</Frame>

### Send usage events to Lago

By running the function in Segment, this will send a test usage to Lago events. You can retrieve this event in the events list. By finalizing the setup in Segment, the function will be automatically triggered based on your defined behavior

## Segment to Lago - demo video

If easier, please find a demo video explaining the full setup of custom functions to send event from Segment.com to Lago.

<iframe width="700" height="500" src="https://www.youtube.com/embed/lyJmdh47JTE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen />


# Clone Segment pricing

Replicate Segment's hybrid pricing model with Lago.

Build a hybrid pricing and billing system like [Segment](https://segment.com/), the Customer Data Platform leader, based on subscription plans, with a usage-based component that makes your revenue grow with your users.

## Summary

<Steps>
  <Step title="Track unique users with a billable metric">
    Meter unique users with a billable metric by using the `unique_count_agg` aggregation type.
    [(More here)](#step-1-keep-track-of-unique-users).
  </Step>

  <Step title="Create a plan with tiers of MTUs">
    Create a new price plan with tiers of tracked users, using the graduated pricing model.
    [(More here)](#step-2-create-a-plan-with-tiers).
  </Step>

  <Step title="Ingest usage for unique users in real-time">
    Ingest raw usage of users that are automatically deduplicated by Lago.
    [(More here)](#step-3-ingest-meter-for-unique-users-in-real-time).
  </Step>
</Steps>

## Pricing structure

Segment offers three pricing plans, called 'Free', 'Team' and 'Business'. As the latter has a custom pricing, we will focus on the first two plans.

| Plan                        | Free plan  | Team plan         |
| --------------------------- | ---------- | ----------------- |
| Subscription Fee            | \$0/month  | \$120/month       |
| Base Consumption (included) | 1,000 MTUs | 10,000 MTUs       |
| Consumption (10k-25k MTUs)  | n/a        | \$0.012/month/MTU |
| Consumption (25k-100k MTUs) | n/a        | \$0.011/month/MTU |
| Consumption (100k+ MTUs)    | n/a        | \$0.010/month/MTU |
| Trial Period                | n/a        | 14 days           |

The usage-based component in Segment's pricing is related to **monthly tracked users (MTUs)**, namely the number of unique users whose data is stored on the platform each month.
As these are **unique users**, we must ensure that each user is counted only once during the billing process.

Now let's see how we can implement Segment's pricing plans using Lago.

## Step 1: Keep track of unique users

Segment has implemented a graduated pricing model, based on the number of MTUs.

| MTUs          | Price        |
| ------------- | ------------ |
| 10k-25k MTUs  | \$0.012/unit |
| 25k-100k MTUs | \$0.011/unit |
| 100k+ MTUs    | \$0.010/unit |

Therefore, we need to calculate the number of unique users in order to implement our second pricing plan.

<Tabs>
  <Tab title="Dashboard">
    We are going to use a billable metric, which will allow us to aggregate incoming events on the platform to measure consumption.

    We have created a billable metric, called **Monthly Tracked Users**, which includes the **`user_id` property**. In addition to this, we have defined `unique_count_agg` as the aggregation type.

    What does this mean? Every time the customer data platform (e.g. Segment) records a new activity, a `mtu` event will be sent to Lago, which will then use the `user_id` property to deduplicate users to get only the total number of unique ones.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/ZmoZUeJrPms?si=U8-dxW9B-Bw81ecK&start=38" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Create a metric tracking unique users
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "billable_metric": {
            "name": "Monthly Tracked Users",
            "code": "mtu",
            "aggregation_type": "unique_count_agg",
            "weighted_interval": null,
            "recurring": false,
            "field_name": "user_id",
            "filters": []
        }
    }'
    ```
  </Tab>
</Tabs>

## Step 2: Create a plan with tiers

It’s time to create our **Team plan**. The subscription part is similar to the 'Free plan' (except that the amount is now \$120). We can also add the 14-day free trial currently offered by Segment.

<Tabs>
  <Tab title="Dashboard">
    To charge customers for consumption (i.e. based on MTUs), we need to add a charge to our plan.
    Using the `mtu` billable metric created previously, we have implemented the graduated pricing model to reproduce Segment's pricing, including 10,000 free units (i.e. 10,000 unique users).

    Following this example, for a customer on the ‘Team’ plan with 30,000 MTUs, at the end of the month, their invoice will amount to:

    *   \$120 (first 10,000 MTUs)
    *   \$180 (next 15,000 MTUs)
    *   \$55 (last 5,000 MTUs)

    Our pricing plan is now ready!

    <iframe width="560" height="315" src="https://www.youtube.com/embed/ZmoZUeJrPms?si=FHyQ9MXqpOOu1AEb&start=103" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Create a plan with tiers of MTUs
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"
    curl --location --request POST "$LAGO_URL/api/v1/plans" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "plan": {
            "name": "Team",
            "code": "team",
            "interval": "monthly",
            "amount_cents": 12000,
            "amount_currency": "USD",
            "trial_period": 0.0,
            "pay_in_advance": true,
            "charges": [
                {
                    "billable_metric_id": "f8e854e5-69a3-420f-88a2-296324ee17d0",
                    "invoice_display_name": null,
                    "billable_metric_code": "mtu",
                    "created_at": "2024-05-03T22:32:09Z",
                    "charge_model": "graduated",
                    "invoiceable": true,
                    "pay_in_advance": false,
                    "prorated": false,
                    "min_amount_cents": 0,
                    "properties": {
                        "graduated_ranges": [
                            {
                                "to_value": 10000,
                                "from_value": 0,
                                "flat_amount": "0",
                                "per_unit_amount": "0"
                            },
                            {
                                "to_value": 20000,
                                "from_value": 10001,
                                "flat_amount": "0",
                                "per_unit_amount": "0.012"
                            },
                            {
                                "to_value": null,
                                "from_value": 20001,
                                "flat_amount": "0",
                                "per_unit_amount": "0.011"
                            }
                        ]
                    },
                    "filters": [],
                    "taxes": []
                }
            ],
            "taxes": []
        }
    }'
    ```
  </Tab>
</Tabs>

## Step 3: Ingest usage for unique users in real-time

<Tabs>
  <Tab title="Dashboard">
    For every user accessing Segment's platform, an event is dispatched containing the `user_id` property. Lago seamlessly handles deduplication to ensure accurate tracking of unique users.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/ZmoZUeJrPms?si=JVOOuCR31m5GwUd4&start=270" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Ingest event for each transaction
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"
    curl --location --request POST "$LAGO_URL/api/v1/events" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "event": {
            "transaction_id": "{{$randomUUID}}",
            "code": "mtu",
            "external_customer_id": "hooli_1234",
            "properties": {
                "user_id": "user_id_001"
            }
        }
    }'
    ```
  </Tab>
</Tabs>

## Wrap-up

Hybrid pricing plans are very popular among SaaS, API, fintech and data companies like Segment.

With Lago, you can easily adapt this template to create your own hybrid pricing plan, using some of our most popular features:

*   **Plan models**, including monthly/yearly plans that can be paid in advance or in arrears;
*   **Billable metrics**, including multiple aggregation types; and
*   **Charges**, including our graduated pricing model (and more).

Give it a try, click [here](https://www.getlago.com/get-started) to get started!


# Introduction

Replicate these popular B2B pricing templates to kickstart your journey with Lago.

Whether you are an API company, a fintech scale-up, an established SaaS provider or an early-stage data platform, find the pricing template that meets your needs and discover how Lago can help you implement it.

## Per-token pricing (AI)

<CardGroup cols={2}>
  <Card
    title="Mistral.ai"
    icon={
     <svg
       width="30px"
       height="30px"
       viewBox="0 0 256 233"
       version="1.1"
       xmlns="http://www.w3.org/2000/svg"
       preserveAspectRatio="xMidYMid"
     >
       <g>
         <rect
           fill="#000000"
           x="186.181818"
           y="0"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#F7D046"
           x="209.454545"
           y="0"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#000000"
           x="0"
           y="0"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#000000"
           x="0"
           y="46.5454545"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#000000"
           x="0"
           y="93.0909091"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#000000"
           x="0"
           y="139.636364"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#000000"
           x="0"
           y="186.181818"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#F7D046"
           x="23.2727273"
           y="0"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#F2A73B"
           x="209.454545"
           y="46.5454545"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#F2A73B"
           x="23.2727273"
           y="46.5454545"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#000000"
           x="139.636364"
           y="46.5454545"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#F2A73B"
           x="162.909091"
           y="46.5454545"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#F2A73B"
           x="69.8181818"
           y="46.5454545"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#EE792F"
           x="116.363636"
           y="93.0909091"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#EE792F"
           x="162.909091"
           y="93.0909091"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#EE792F"
           x="69.8181818"
           y="93.0909091"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#000000"
           x="93.0909091"
           y="139.636364"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#EB5829"
           x="116.363636"
           y="139.636364"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#EE792F"
           x="209.454545"
           y="93.0909091"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#EE792F"
           x="23.2727273"
           y="93.0909091"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#000000"
           x="186.181818"
           y="139.636364"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#EB5829"
           x="209.454545"
           y="139.636364"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#000000"
           x="186.181818"
           y="186.181818"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#EB5829"
           x="23.2727273"
           y="139.636364"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#EA3326"
           x="209.454545"
           y="186.181818"
           width="46.5454545"
           height="46.5454545"
         ></rect>
         <rect
           fill="#EA3326"
           x="23.2727273"
           y="186.181818"
           width="46.5454545"
           height="46.5454545"
         ></rect>
       </g>
     </svg>
    }
    href="/templates/per-token/mistral"
  >
    Build a transparent per-token pricing like Mistral, the famous AI company,
    with multiple dimensions and prepaid credits.
  </Card>

  <Card
    title="OpenAI"
    icon={
     <svg
       width="30px"
       height="30px"
       viewBox="0 0 512 512"
       xmlns="http://www.w3.org/2000/svg"
       fill-rule="evenodd"
       clip-rule="evenodd"
       stroke-linejoin="round"
       stroke-miterlimit="2"
     >
       <path
         d="M474.123 209.81c11.525-34.577 7.569-72.423-10.838-103.904-27.696-48.168-83.433-72.94-137.794-61.414a127.14 127.14 0 00-95.475-42.49c-55.564 0-104.936 35.781-122.139 88.593-35.781 7.397-66.574 29.76-84.637 61.414-27.868 48.167-21.503 108.72 15.826 150.007-11.525 34.578-7.569 72.424 10.838 103.733 27.696 48.34 83.433 73.111 137.966 61.585 24.084 27.18 58.833 42.835 95.303 42.663 55.564 0 104.936-35.782 122.139-88.594 35.782-7.397 66.574-29.76 84.465-61.413 28.04-48.168 21.676-108.722-15.654-150.008v-.172zm-39.567-87.218c11.01 19.267 15.139 41.803 11.354 63.65-.688-.516-2.064-1.204-2.924-1.72l-101.152-58.49a16.965 16.965 0 00-16.687 0L206.621 194.5v-50.232l97.883-56.597c45.587-26.32 103.732-10.666 130.052 34.921zm-227.935 104.42l49.888-28.9 49.887 28.9v57.63l-49.887 28.9-49.888-28.9v-57.63zm23.223-191.81c22.364 0 43.867 7.742 61.07 22.02-.688.344-2.064 1.204-3.097 1.72L186.666 117.26c-5.161 2.925-8.258 8.43-8.258 14.45v136.934l-43.523-25.116V130.333c0-52.64 42.491-95.13 95.131-95.302l-.172.172zM52.14 168.697c11.182-19.268 28.557-34.062 49.544-41.803V247.14c0 6.02 3.097 11.354 8.258 14.45l118.354 68.295-43.695 25.288-97.711-56.425c-45.415-26.32-61.07-84.465-34.75-130.052zm26.665 220.71c-11.182-19.095-15.139-41.802-11.354-63.65.688.516 2.064 1.204 2.924 1.72l101.152 58.49a16.965 16.965 0 0016.687 0l118.354-68.467v50.232l-97.883 56.425c-45.587 26.148-103.732 10.665-130.052-34.75h.172zm204.54 87.39c-22.192 0-43.867-7.741-60.898-22.02a62.439 62.439 0 003.097-1.72l101.152-58.317c5.16-2.924 8.429-8.43 8.257-14.45V243.527l43.523 25.116v113.022c0 52.64-42.663 95.303-95.131 95.303v-.172zM461.22 343.303c-11.182 19.267-28.729 34.061-49.544 41.63V264.687c0-6.021-3.097-11.526-8.257-14.45L284.893 181.77l43.523-25.116 97.883 56.424c45.587 26.32 61.07 84.466 34.75 130.053l.172.172z"
         fill-rule="nonzero"
       />
     </svg>
    }
    href="/templates/per-token/openai"
  >
    Replicate OpenAI's per-token pricing, the famous AI company behind GPT
    models, with multiple dimensions based on models and action types.
  </Card>
</CardGroup>

## Hybrid pricing

<CardGroup cols={2}>
  <Card
    title="Segment"
    icon={
     <svg
       width="35"
       height="35"
       enable-background="new 0 0 1024 1024"
       viewBox="0 0 1024 1024"
       xmlns="http://www.w3.org/2000/svg"
     >
       <circle cx="512" cy="512" fill="#52bd94" r="512" />
       <path
         d="m346.8 654.5c-16 0-29 13-29 29s13 29 29 29 29-13 29-29-13-29-29-29zm319.9-350.5c-16 0-29.1 12.9-29.1 29 0 16 12.9 29.1 29 29.1 16 0 29.1-12.9 29.1-29 0 0 0 0 0-.1 0-16-13-29-29-29zm-210.1 117.2v35.6c0 5.3 4.3 9.7 9.7 9.7h287.4c5.3 0 9.7-4.3 9.7-9.7v-35.6c0-5.3-4.4-9.7-9.7-9.7h-287.4c-5.4.1-9.7 4.4-9.7 9.7zm110.6 164.1v-35.5c0-5.3-4.3-9.7-9.7-9.7h-287.4c-5.3 0-9.7 4.3-9.7 9.7v35.5c0 5.3 4.3 9.7 9.7 9.7h287.4c5.4 0 9.7-4.3 9.7-9.7zm194-47.8c-1.6-2-3.8-3.3-6.4-3.6l-35.3-3.6c-5.2-.6-9.9 3.1-10.6 8.3-14.8 110.2-116.3 187.6-226.5 172.7-15.3-2.1-30.3-5.9-44.7-11.3-4.9-1.9-10.4.4-12.3 5.3l-13.5 32.7c-1 2.4-1 5.1 0 7.5s3 4.4 5.5 5.3c131.9 50.9 280.2-14.8 331.1-146.7 7.4-19.1 12.4-39 15-59.3.3-2.7-.5-5.3-2.3-7.3zm-498.7-81.6c-1.4-2.2-1.8-4.9-1.1-7.4 29-113.3 131.1-192.5 248-192.4 28.6 0 57.1 4.7 84.1 14.2 5 1.6 7.8 7 6.2 12-.1.2-.2.5-.3.7l-12.7 33.2c-1.8 4.9-7.2 7.5-12.1 5.7-21-7.2-43.1-10.8-65.3-10.8-46-.2-90.6 15.5-126.3 44.5-33.5 27.1-57.4 64.2-68.4 105.8-1.1 4.2-4.9 7.2-9.3 7.2-.7.1-1.5.1-2.2 0l-34.6-7.9c-2.6-.8-4.7-2.5-6-4.8z"
         fill="#fff"
       />
     </svg>
    }
    href="/templates/hybrid/segment"
  >
    Build a hybrid pricing and billing system like Segment, the CDP leader,
    based on subscription plans, with a usage-based component that makes your
    revenue grow with your users.
  </Card>
</CardGroup>

## Per-transaction pricing

<CardGroup cols={2}>
  <Card
    title="Stripe"
    icon={
     <svg
       width="30"
       height="30"
       viewBox="0 0 40 40"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <rect width="40" height="40" rx="12" fill="#6772E5" />
       <path
         d="M18.5779 15.956C18.5779 15.099 19.2834 14.7692 20.4521 14.7692C22.1276 14.7692 24.2441 15.2748 25.9197 16.1759V11.011C24.0898 10.2857 22.282 10 20.4521 10C15.9764 10 13 12.3297 13 16.22C13 22.2857 21.3779 21.3188 21.3779 23.9343C21.3779 24.9451 20.4961 25.2748 19.2614 25.2748C17.4316 25.2748 15.0945 24.5275 13.2425 23.5166V28.7474C15.2929 29.6265 17.3654 30 19.2614 30C23.8472 30 27 27.7364 27 23.8023C26.978 17.2529 18.5779 18.4176 18.5779 15.956Z"
         fill="white"
       />
     </svg>
    }
    href="/templates/per-transaction/stripe"
  >
    Implement a per-transaction pricing model like Stripe, the leading payments
    infrastructure company, including fees based on the total amount and number
    of transactions.
  </Card>
</CardGroup>

## Pay-as-you-go pricing

<CardGroup cols={2}>
  <Card
    title="Algolia"
    icon={
     <svg
       width="30"
       height="30"
       viewBox="0 0 40 40"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <path
         d="M5.26659 0H34.7331C37.633 0 40.0004 2.35498 40.0004 5.2666V34.735C40.0004 37.635 37.6451 40 34.7331 40H5.26659C2.3666 40 0 37.6466 0 34.735V5.25337C0 2.35498 2.35326 0 5.26659 0Z"
         fill="#5468FF"
       />
       <path
         d="M24.1681 8.92938V7.55774C24.1681 7.09739 23.9852 6.65605 23.6588 6.33069C23.3335 6.00534 22.8919 5.82265 22.4311 5.82275H18.3831C17.9229 5.82265 17.4813 6.00534 17.1557 6.33069C16.83 6.65605 16.6468 7.09739 16.6465 7.55774V8.96606C16.6465 9.12278 16.7915 9.23271 16.9498 9.19603C18.095 8.86542 19.2812 8.6982 20.473 8.69941C21.6279 8.69941 22.7717 8.85603 23.876 9.15935C24.0236 9.19603 24.1681 9.08772 24.1681 8.92938ZM13.0732 10.7244L12.3814 10.0328C12.2203 9.87149 12.029 9.74347 11.8183 9.65628C11.6078 9.56898 11.3819 9.52401 11.154 9.52401C10.926 9.52401 10.7002 9.56898 10.4896 9.65628C10.279 9.74347 10.0876 9.87149 9.92652 10.0328L9.0998 10.8578C8.93824 11.0183 8.80992 11.2094 8.72241 11.4198C8.63491 11.6301 8.58984 11.8558 8.58984 12.0836C8.58984 12.3114 8.63491 12.537 8.72241 12.7474C8.80992 12.9578 8.93824 13.1488 9.0998 13.3094L9.77982 13.9893C9.88985 14.0978 10.0482 14.0727 10.1448 13.9644C10.546 13.4134 10.989 12.8941 11.4698 12.4111C11.9547 11.9246 12.4786 11.4786 13.0365 11.0777C13.1578 11.0044 13.1699 10.8344 13.0732 10.7244ZM20.4608 15.0794V21.0128C20.4608 21.1827 20.6447 21.3044 20.8013 21.2194L26.0757 18.4894C26.196 18.4294 26.2323 18.2827 26.1727 18.1628C25.0795 16.2444 23.0495 14.9344 20.7043 14.8494C20.5831 14.8494 20.4608 14.946 20.4608 15.0794ZM20.4608 29.3728C16.0628 29.3728 12.4895 25.8044 12.4895 21.4127C12.4895 17.0211 16.0628 13.4544 20.4608 13.4544C24.8612 13.4544 28.433 17.0211 28.433 21.4127C28.433 25.8044 24.8733 29.3728 20.4608 29.3728ZM20.4608 10.106C14.2144 10.106 9.1478 15.1661 9.1478 21.4127C9.1478 27.6611 14.2144 32.7095 20.4608 32.7095C26.7082 32.7095 31.7745 27.6494 31.7745 21.4011C31.7745 15.1527 26.7194 10.106 20.4608 10.106Z"
         fill="white"
       />
     </svg>
    }
    href="/templates/payg/algolia"
  >
    Discover how Algolia, the search and discovery platform, increases
    conversion with commitment-free pricing options that adapt to customers’
    needs.
  </Card>

  <Card
    title="Google BigQuery"
    icon={
    <svg
     width="30"
     height="30"
     viewBox="0 0 40 40"
     fill="none"
     xmlns="http://www.w3.org/2000/svg"
    >
    <path d="M36.5364 20.2896C36.5364 19.0685 36.4268 17.8943 36.2233 16.7671H20.0039V23.4364H29.2721C28.8651 25.5813 27.6439 27.3973 25.8122 28.6185V32.9551H31.4013C34.6577 29.9492 36.5364 25.5343 36.5364 20.2896Z" fill="#4285F4"/>
    <path d="M20.0068 37.1177C24.6565 37.1177 28.5548 35.5834 31.4041 32.9533L25.815 28.6166C24.2808 29.6499 22.3238 30.2761 20.0068 30.2761C15.5292 30.2761 11.7249 27.2546 10.3628 23.1841H4.63281V27.6303C7.4665 33.2507 13.2748 37.1177 20.0068 37.1177Z" fill="#34A853"/>
    <path d="M10.3625 23.1695C10.0181 22.1363 9.81459 21.0403 9.81459 19.8975C9.81459 18.7546 10.0181 17.6587 10.3625 16.6254V12.1792H4.63253C3.45835 14.4962 2.78516 17.1108 2.78516 19.8975C2.78516 22.6842 3.45835 25.2987 4.63253 27.6158L9.09442 24.1402L10.3625 23.1695Z" fill="#FBBC05"/>
    <path d="M20.0068 9.53349C22.543 9.53349 24.7974 10.4102 26.5978 12.101L31.5294 7.16947C28.5391 4.38275 24.6565 2.67627 20.0068 2.67627C13.2748 2.67627 7.4665 6.54324 4.63281 12.1793L10.3628 16.6255C11.7249 12.555 15.5292 9.53349 20.0068 9.53349Z" fill="#EA4335"/>
     <path
     />
    </svg>
    }
    href="/templates/payg/bigquery"
  >
    Implement a pay-as-you-go pricing model and offer free upfront credits to new users like Google BigQuery, the data analytics plaform.
  </Card>
</CardGroup>

## Per-seat pricing

<CardGroup cols={2}>
  <Card
    title="Notion"
    icon={
     <svg
       width="30"
       height="30"
       viewBox="0 0 39 40"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
     >
       <path
         d="M3.07472 1.72564L25.2075 0.0908753C27.9262 -0.14232 28.6246 0.0148767 30.3342 1.25765L37.3993 6.23476C38.5644 7.09074 38.9524 7.32394 38.9524 8.25592V35.5526C38.9524 37.2634 38.3312 38.2753 36.1565 38.4297L10.4546 39.9865C8.82261 40.0637 8.04543 39.8305 7.19064 38.7413L1.98794 31.9759C1.05476 30.7307 0.667969 29.7987 0.667969 28.7091V4.44559C0.667969 3.04682 1.28916 1.88044 3.07472 1.72564Z"
         fill="white"
       />
       <path
         fill-rule="evenodd"
         clip-rule="evenodd"
         d="M25.2075 0.0912753L3.07472 1.72604C1.28916 1.88044 0.667969 3.04722 0.667969 4.44559V28.7091C0.667969 29.7983 1.05476 30.7303 1.98794 31.9759L7.19064 38.7409C8.04543 39.8301 8.82261 40.0637 10.4546 39.9861L36.1569 38.4301C38.33 38.2753 38.9528 37.2634 38.9528 35.553V8.25632C38.9528 7.37233 38.6036 7.11754 37.5757 6.36315L30.3342 1.25765C28.625 0.0148767 27.9262 -0.14232 25.2075 0.0908753V0.0912753ZM11.0358 7.80953C8.93701 7.95072 8.46102 7.98272 7.26904 7.01354L4.2387 4.60319C3.93071 4.29119 4.0855 3.902 4.86149 3.8244L26.1383 2.26963C27.925 2.11364 28.8554 2.73642 29.5542 3.28041L33.2033 5.92436C33.3593 6.00316 33.7473 6.46835 33.2805 6.46835L11.3078 7.79113L11.0358 7.80953ZM8.58902 35.3198V12.147C8.58902 11.1351 8.89981 10.6683 9.83019 10.5899L35.0673 9.1123C35.9233 9.0351 36.3101 9.57909 36.3101 10.5895V33.6078C36.3101 34.6198 36.1541 35.4758 34.7569 35.553L10.6066 36.953C9.2094 37.0302 8.58942 36.565 8.58942 35.3198H8.58902ZM32.4286 13.3894C32.5834 14.0894 32.4286 14.7894 31.7286 14.8694L30.5646 15.1002V32.2091C29.5538 32.753 28.6234 33.0638 27.8458 33.0638C26.6031 33.0638 26.2927 32.6746 25.3619 31.5091L17.75 19.5333V31.1199L20.158 31.6651C20.158 31.6651 20.158 33.065 18.2152 33.065L12.8593 33.3758C12.7033 33.0638 12.8593 32.2867 13.4021 32.1319L14.8009 31.7439V16.4242L12.8597 16.267C12.7037 15.567 13.0917 14.5562 14.1797 14.4778L19.9264 14.091L27.8462 26.2216V15.4898L25.8275 15.2578C25.6715 14.4006 26.2927 13.7778 27.0687 13.7018L32.4286 13.3894Z"
         fill="black"
       />
     </svg>
    }
    href="/templates/per-seat/notion"
  >
    Set up a per-user pricing like Notion, the collaboration software for
    innovative teams, including plans based on the number of users and prepaid
    credits.
  </Card>
</CardGroup>


# Clone Algolia pricing

Replicate Algolia's pay-as-you-go pricing model with Lago.

In this article, you will learn how to build a ‘pay-as-you-go’ billing system.
This template is suitable for companies whose pricing fully depends on usage, such as cloud service providers and API companies, that only charge their customers for the resources they consume.

## Summary

<Steps>
  <Step title="Aggregate usage to compute number of requests">
    Create a billable metric to track request usage.
    [(More here)](#step-1-aggregate-usage-with-filters).
  </Step>

  <Step title="Create a plan with multiple charges">
    Set up a package pricing model.
    [(More here)](#step-2-set-up-a-per-token-pricing).
  </Step>

  <Step title="Offer volume and commitment discounts">
    Leverage subscriptions for a reduced price.
    [(More here)](#step-3-ingest-usage-in-real-time).
  </Step>
</Steps>

## Pricing structure

For its two main products, Algolia Search and Algolia Recommend, the platform offers its customers to subscribe for free and only pay based on usage.

| Model                   | Search API              | Recommend API           |
| ----------------------- | ----------------------- | ----------------------- |
| Monthly price           | \$1.50 / 1,000 requests | \$0.60 / 1,000 requests |
| Free usage (each month) | 10,000 requests         | 10,000 requests         |

Although users don’t need to subscribe to access the platform, Algolia offers its customers **discounts** based on volume and commitment (rates available upon request).
We are going to teach you how to replicate this pricing with our billing solution.

## Step 1: Aggregate usage to compute number of requests

Lago monitors consumption by converting events into billable metrics. For Algolia, there would be two billable metrics based on the number of requests for the Search and Recommendation APIs.
As the platform handles **high volumes of requests**, it would be inefficient to create an event each time a request is made. Instead, Algolia could simply send an event once an hour or hour a day with the total number of requests.

<Tabs>
  <Tab title="Dashboard">
    Through the user interface, we have created two billable metrics called **‘Search requests’** and **‘Recommend requests’**. For these metrics, we use the ‘sum’ aggregation type based on the volume of requests.
    At the end of the billing period, Lago will calculate the sum of requests for each metric using the value of each event (i.e. the event property) and reset the amount to 0 as the aggregation type is metered.

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/algolia-aggregate-requests.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    ```bash Create billable metrics
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"

        curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "billable_metric": {
            "name": "Search Requests",
            "code": "search_requests",
            "description": "Requests made via the Search API",
            "aggregation_type": "sum_agg",
            "weighted_interval": null,
            "recurring": false,
            "field_name": "search_requests_volume",
            "filters": []
          }
        }

    ```
  </Tab>
</Tabs>

## Step 2: Create a plan with multiple charges

Now that we have all our billable metrics, we can replicate Algolia’s pricing. As this is a ‘pay-as-you-go’ plan, there is no subscription fee. In the plan settings, we can simply define a monthly billing period and then add our charges.

<Tabs>
  <Tab title="Dashboard">
    For both charges, we use the **package pricing model**. This model allows us to create packages of units and define a unique package price. Customers will be charged for usage based on packages of 1,000 requests. Algolia offers 10,000 requests for free each month, for both APIs. Beyond this limit, each ‘opened’ package is due, which means that 800 Search requests cost the same price as 1,000 requests (i.e. \$1.50).
    At the end of each billing period (i.e. each month), Lago will automatically invoice each customer according to their consumption, then all counts and calculations will be reset to zero for the next period.

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/algolia-package-pricing.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    ```bash Create a plan with multiple charges
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"
        curl --location --request POST "$LAGO_URL/api/v1/plans" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
         "plan": {
              "name": "Algolia Starter",
              "code": "algolia_starter",
              "interval": "monthly",
              "amount_cents": 0,
              "amount_currency": "USD",
              "trial_period": 0.0,
              "pay_in_advance": false,
              "charges": [
                  {
                      "billable_metric_id": "15879740-102e-43bd-a6bc-15d865bb1b85",
                      "billable_metric_code": "search_requests",
                      "charge_model": "package",
                      "invoiceable": true,
                      "pay_in_advance": false,
                      "prorated": false,
                      "min_amount_cents": 0,
                      "properties": {
                          "amount": "1.50",
                          "free_units": 10000,
                          "package_size": 1000
                      },
                      "filters": [],
                      "taxes": []
                  }
              ],
          }
        }



    ```
  </Tab>
</Tabs>

## Step 3: Offer volume and commitment discounts through subscriptions

*“When committing to the equivalent of 100 Search units per month or more, you automatically unlock a discount compared to PAYGO. Please contact sales for more information.”*

Algolia doesn't provide much information about their volume and commitment discounts but we know that customers who commit to making at least 100,000 Search requests per month (for Algolia, a “Search unit” is a package of 1,000 requests) can benefit from a **reduced price**.
We are going to make some assumptions to see how we could implement this logic.

If we want to keep our package pricing model, we should convert the commitment part of our plan into a **subscription**.

<Tabs>
  <Tab title="Dashboard">
    With the standard pricing, 100,000 requests would be charged \$150 (i.e. 100 packages of 1,000 requests at \$1.50 each). Since we want to offer a discount to our customers, we can create a new plan with a monthly subscription of \$120, paid in advance. Then, we set the package price for 1000 requests at \$1.20. Also, we include 100,000 free units, which are covered by the subscription fee.

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/algolia-subscription.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    ```bash Introduce a subscription
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"
        curl --location --request POST "$LAGO_URL/api/v1/plans" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
            "plan": {
              "name": "Algolia committed",
              "code": "algolia_committed",
              "interval": "monthly",
              "amount_cents": 12000,
              "amount_currency": "USD",
              "trial_period": 0.0,
              "pay_in_advance": true,
              "charges": [
                  {
                      "billable_metric_id": "15879740-102e-43bd-a6bc-15d865bb1b85",
                      "billable_metric_code": "search_requests",
                      "charge_model": "package",
                      "invoiceable": true,
                      "pay_in_advance": false,
                      "prorated": false,
                      "min_amount_cents": 0,
                      "properties": {
                          "amount": "1.20",
                          "free_units": 10000,
                          "package_size": 1000
                      },
                      "filters": [],
                      "taxes": []
                  }
              ],
              "taxes": []
          }

    ```
  </Tab>
</Tabs>

Another option would be to drop the package pricing model and use the **graduated pricing model**. This model would allow us to create several tiers with different unit prices.

<Tabs>
  <Tab title="Dashboard">
    For the first 100,000 requests included in the subscription, we set a flat fee of \$0 and then apply a decreasing unit price to offer a volume discount.

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/algolia-volume-discount.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    ```bash Implement volume discount
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"
        curl --location --request POST "$LAGO_URL/api/v1/plans" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "plan": {
              "name": "Algolia committed",
              "code": "algolia_committed",
              "interval": "monthly",
              "amount_cents": 12000,
              "amount_currency": "USD",
              "trial_period": 0.0,
              "pay_in_advance": true,
              "charges": [
                  {
                      "billable_metric_id": "15879740-102e-43bd-a6bc-15d865bb1b85",
                      "billable_metric_code": "search_requests",
                      "charge_model": "graduated",
                      "invoiceable": true,
                      "pay_in_advance": false,
                      "prorated": false,
                      "min_amount_cents": 0,
                      "properties": {
                          "graduated_ranges": [
                              {
                                  "to_value": 100000,
                                  "from_value": 0,
                                  "flat_amount": "0",
                                  "per_unit_amount": "0"
                              },
                              {
                                  "to_value": 150000,
                                  "from_value": 100001,
                                  "flat_amount": "0",
                                  "per_unit_amount": "0.0011"
                              },
                              {
                                  "to_value": null,
                                  "from_value": 150001,
                                  "flat_amount": "0",
                                  "per_unit_amount": "0.001"
                              }
                          ]
                      },
                      "filters": [],
                      "taxes": []
                  }
              ],
              "taxes": []
          }

    ```
  </Tab>
</Tabs>

## Wrap-up

‘Pay-as-you-go’ pricing strategies are popular among API companies like Algolia.
With Lago, you can adapt this template to your products and services, using some of our most popular features:

1.  **Plan models**, with or without subscription;‍
2.  **Billable metrics**, including the ‘sum’ aggregation type; and‍
3.  **Charges**, including our package and graduated pricing models.

Give it a try, click [here](https://www.getlago.com/get-started) to get started!


# Clone Google BigQuery pricing

Replicate BigQuery's pay-as-you-go pricing model and offer free upfront credits with Lago.

In this article, you will learn how to offer free upfront credits for new users on a ‘pay-as-you-go’ pricing model.
This template is fitted for infra companies, like this BigQuery example, but is also widely used among AI companies to let new users try their products easily.
[Mistral](https://mistral.ai/news/2024-ft-hackathon/#:~:text=We%20offer%20%24100%20free%20credits%20to%20selected%20hackathon%20participants) or [Perplexity](https://docs.perplexity.ai/docs/pricing#:~:text=pplx%2Dapi%20implements%20a%20usage,of%20free%20credit%20every%20month) are other great examples.

## Summary

<Steps>
  <Step title="Configure your pay-as-you-go model to compute usage">
    Aggregate usage to compute number of requests.
    [(More here)](#aggregate-usage-to-compute-number-of-requests).

    Create a plan with graduated charges.
    [(More here)](#create-a-plan-with-graduated-charges).
  </Step>

  <Step title="Create a wallet to offer free upfront credits">
    Set up free credits.
    [(More here)](#step-2-create-a-wallet-to-offer-free-credits).
  </Step>

  <Step title="Record customer usage to start invoicing">
    Send usage events to get started.
    [(More here)](#step-3-record-customer-usage-to-start-invoicing-customers).
  </Step>
</Steps>

## Pricing structure

BigQuery offers customers the possibility to subscribe for free and only pay based on usage. For new customers, the platform offers \$300 worth of credits during 90 days to try the product completely for free.

| Plan              | Cost per volume of data scanned                |
| ----------------- | ---------------------------------------------- |
| On-Demand pricing | \$6.25 per TiB (a measure of compute capacity) |

In this article, we are going to show you how to replicate this pricing with Lago’s billing solution.

## Step 1: Configure your pay-as-you-go pricing

### Aggregate usage to compute number of requests

Lago’s **billable metric** allows you to meter and aggregate customer events according to specific rules. For BigQuery, the billable metric will sum the total volume of data scanned.

As the platform handles high volumes of requests, it would be inefficient to create an event each time a query is made.
Instead, BigQuery could simply send an event once an hour or hour a day with the total volume of data processed.

<Tabs>
  <Tab title="Dashboard">
    Through the user interface, we created one ‘Data processed’ **billable metric**. For this metric, we use the `sum` aggregation type based on the volume of data processed.
    At the end of the billing period, Lago calculates the total volume of processed data for the billable metric using the value contained in each event (i.e. the event property) and reset the amount to 0 as the aggregation type is **metered**.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/EaRi97Q2BcQ?si=n1WP-vIdVvUzzk3v&start=67" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Create billable metrics
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"
        
        curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
            "billable_metric": {
            "name": "Data processed",
            "code": “data_processed",
            "description": "Total volume of data scanned by BigQuery",
            "aggregation_type": "sum",
            "recurring": false,
            "field_name": "data_processed_volume",
            "filters": [
            ]
          }
        }'


    ```
  </Tab>
</Tabs>

### Create a plan with graduated charges

We now have our billable metric to replicate BigQuery’s pricing. As this is a ‘pay-as-you-go’ plan, there is no subscription fee.
In the plan setting, we only need to define a monthly billing period and set a specific pricing to our charges.

<Tabs>
  <Tab title="Dashboard">
    We use the **graduated charge** model since BigQuery offers the first unit for free.
    At the end of each billing period (i.e. each month), Lago will automatically invoice each customer according to their consumption, then all counts and calculations will be reset to zero for the next period.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/EaRi97Q2BcQ?si=W0MVC4efSRY9ujZt&start=125" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Create a plan with graduated charges
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"
        curl --location --request POST "$LAGO_URL/api/v1/plans" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
         "plan": {
              "name": "BigQuery On-Demand",
              "code": "bigquery_on_demand",
              "interval": "monthly",
              "amount_cents": 0,
              "amount_currency": "USD",
              "trial_period": 0.0,
              "pay_in_advance": false,
              "charges": [
                  {
                      "billable_metric_id": "__BILLABLE_METRIC_ID__",
                      "billable_metric_code": "data_processed",
                      "charge_model": "graduated",
                      "invoiceable": true,
                      "pay_in_advance": false,
                      "prorated": false,
                      "min_amount_cents": 0,
            "properties": {
              "graduated_ranges": [
                {
                  "from_value": 0,
                  "to_value": 10000,
                  "per_unit_amount": "0",
                  "flat_amount": "0"
                },
                {
                  "from_value": 10001,
                  "to_value": null,
                  "per_unit_amount": "6.25",
                  "flat_amount": "0"
                }
              ]
            },
                      "filters": [],
                      "taxes": []
                  }
              ],
          }
        }


    ```
  </Tab>
</Tabs>

## Step 2: Create a wallet to offer free credits

*“Start your 90-day free BigQuery trial which includes \$300 worth of free usage”*

BigQuery lets new users try its product for free by offering upfront credits valid for 90 days.
We can replicate this logic using Lago’s **wallet** feature and add **prepaid free credits** to it.

<Tabs>
  <Tab title="Dashboard">
    For each customer, we need to create a wallet and offer \$300 of upfront free credits to replicate BigQuery’s offer. To do so, we set up the value of each credit at \$1.00 and grant 300 credits that customers will receive when creating their account.
    The credits are valid for 90 days, so we will also set an expiration date on the wallet. After this date, the wallet will expire and all remaining credits won’t be actionable.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/EaRi97Q2BcQ?si=W0MVC4efSRY9ujZt&start=222" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Create a wallet on a customer
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"
        curl --location --request POST "https://api.getlago.com/api/v1/wallets" \
        --header "Authorization: Bearer $__YOUR_API_KEY__" \
        --header 'Content-Type: application/json' \
        --data-raw '{
          "wallet": {
              "name": "Free trial offer",
              "rate_amount": "1.00",
              "currency": "USD",
              "external_customer_id": "__EXTERNAL_CUSTOMER_ID__",
              "paid_credits": "0",
              "granted_credits": "30000"
          }
        }'


    ```
  </Tab>
</Tabs>

## Step 3: Record customer usage to start invoicing customers

Once you have set up a billable metric, plan and wallet, you can start sending customer usage events to Lago. Events will be aggregated per the billable metric rules and Lago will price it charges according to the charges defined in the plan.
You can send an event once an hour or hour a day with the total volume of data processed. You can batch up to 100 events in a single request.

<Tabs>
  <Tab title="API">
    ```bash Send usage events
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"
        curl --location --request POST "$LAGO_URL/api/v1/events" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
              "event": {
                  "transaction_id": "__UNIQUE_ID__",
                  "external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
                  "code": "__BILLABLE_METRIC_CODE__",
                  "timestamp": $(date +%s),
                 "properties": {
                    "data_processed_volume": "10"
            },      

                  }
              }
          }'


    ```

    <iframe width="560" height="315" src="https://www.youtube.com/embed/EaRi97Q2BcQ?si=W0MVC4efSRY9ujZt&start=342" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>
</Tabs>

Lago’s engine will compute the ongoing wallet balance based on the customer usage. At the end of the plan’s billing cycle, if the wallet balance is positive, an invoice will be generated but the offered credits will cover the customer usage. On the contrary, if the wallet balance is negative, the outstanding amount will be invoiced to the customer for payment.

Below is an invoice example where the usage exceeded the offered credits. Credits are automatically deducted from the amount due.

<Frame>
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/bigquery-invoice.png" />
</Frame>

## Wrap-up

Offering free upfront credits is a popular strategy among AI and infra companies with pay-as-you-go models like BigQuery.
With Lago, you can adapt this template to your products and services using:

1.  Configure your pay-as-you-go pricing by aggregate using a **billable metric**;‍
2.  Add this billable metric as **graduated charges** to a plan; and‍
3.  Create a **wallet** and add prepaid free credits.

Give it a try, click [here](https://www.getlago.com/get-started) to get started!


# Clone Notion pricing

Replicate Notion's per-seat pricing model with Lago.

Set up a per-user (or 'per-seat) pricing like [Notion](https://www.notion.so/product), the collaboration software for innovative teams, including plans based on the number of users and prepaid credits.

In this article, you will learn how to build a 'fair' billing system, with charges calculated according to the number of days of use.

This template is suitable for companies whose pricing depends on persistent metrics, such as productivity software (e.g. number of days users are active), fintechs (e.g. number of days payment cards are active) and data platforms (e.g. number of days integrations are active).

## Summary

<Steps>
  <Step title="Create recurring metrics">
    Create a billable metric to track user activity. [(More
    here)](#step-1-create-recurring-metrics).
  </Step>

  <Step title="Set up a 'fair' pricing model">
    Set up prorata pricing for a pay-as-you-go plan. [(More
    here)](#step-2-set-up-a-fair-pricing-model).
  </Step>

  <Step title="Offer credits to your customers">
    Create a wallet to assign credits. [(More
    here)](#step-3-offer-credits-to-your-customers).
  </Step>
</Steps>

## Pricing structure

Notion offers a Personal Pro plan for individuals who want to collaborate with friends or clients, and a Team plan through which members can set up a collaborative workspace. While the Personal Pro plan is limited to one member, the Team plan allows companies to invite as many members as they need.

| Model                   | Personal Pro plan  | Team plan                    |
| ----------------------- | ------------------ | ---------------------------- |
| Pages and blocks        | Unlimited          | Unlimited                    |
| Members                 | Just one           | Unlimited                    |
| Guests                  | Unlimited          | Unlimited                    |
| File uploads            | Unlimited          | Unlimited                    |
| Collaborative workspace | No                 | Yes                          |
| Price                   | \$5 billed monthly | \$10 per user billed monthly |

In its FAQ section, Notion explains how adding and removing members work:

*"If you added members, your account will be charged a prorated amount based on the percentage of the billing cycle left at the time each member was added. If you removed members, your account will be credited in the same way."*

Notion's per-seat pricing is what we call a **'fair' pricing model**, where fees are calculated based on the number of days each user is active.

In addition to this, users can complete tasks to earn credits with which they can pay their Notion bill:

*"You can earn credit by using Notion across your devices and trying out new features. Go to the Earn Credit tab in Settings & Members to learn more."*

Here's how you can replicate this pricing and billing system with Lago.

## Step 1: Create recurring metrics

Lago monitors usage by converting events into billable metrics. Notion's pricing is based on users, so we need to create a billable metric to keep track of the users associated with each customer account.

There are two types of metrics:

*   **Metered metrics** that are reset to zero at the end of each billing period; and
*   **Recurring metrics** that can be carried over several billing periods.

When a new member is added to a Notion account, they are likely to remain active for some time (probably more than just a month). Therefore, we should create a recurring metric for our users.

<Tabs>
  <Tab title="Dashboard">
    The aggregation type is a recurring **count unique** and will allow us to record the period of activity of each user (i.e. from the day the member is added to the account until the day they are removed).

    When a new member is successfully added to the customer account, the backend system will generate an event, including the **user\_id** and **"operation\_type": "add"**. When a member is removed from the customer account, the backend system will also generate an event, including the **user\_id** and **"operation\_type": "remove"**.

    At the end of the billing period, Lago will automatically calculate the number of days of activity for each user.

    <Frame caption="How to create a recurring metric">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/notion-recurring-metric.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    ```bash
    # Create a recurring billable metric
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "billable_metric": {
        "name": "Users",
        "code": "users",
        "description": "Team members with access to the collaborative space",
        "aggregation_type": "unique_count_agg",
        "weighted_interval": null,
        "recurring": true,
        "field_name": "user_id",
        "filters": []
      }
    }
    ```
  </Tab>
</Tabs>

## Step 2: Set up a 'fair' pricing model

When creating a new plan, the first step is to define the plan model, including billing frequency and subscription fee. Notion's Team plan is **'pay-as-you-go'**, which means that there's no subscription fee (i.e. customers only pay for what they use).

<Tabs>
  <Tab title="Dashboard">
    This plan can be billed annually (\$96 per user) or monthly (\$10 per user). Depending on the billing cycle, we add a **standard charge** of \$96 or \$10, associated with our billable metric. For example, for the monthly plan, one unit represents one active user for a full month.

    We turn **Prorate charge amount** on so that when a new user is added in the middle of the billing cycle, they will be billed a prorated amount that corresponds to the percentage of the billing cycle remaining. This same logic is also applied when users are removed.

    <Frame caption="How to create a 'pay-as-you-go' plan">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/notion-plan-per-seat.png" />
    </Frame>

    To understand how it works, we can add a new customer and assign them the monthly Team plan we just created. Today is October 9th and a member is immediately added to the customer account. In the **debugger**, we can see the corresponding event, sent by the backend system via the API.

    <Frame caption="Example of event when adding a user">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/notion-add-user-event.png" />
    </Frame>

    In the **'Usage' tab** of the customer view, we can see that the customer's current usage is \$7.42. As there's one active user and 23 days left in October (including October 9th), the billing system plans to bill 0.74194 units at the end of the period (23 days left divided by 31 days in October).

    <Frame caption="Usage report updated in real time">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/notion-usage-report.png" />
    </Frame>
  </Tab>

  <Tab title="API">
    ```bash
    # Create a plan with prorata
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"
    curl --location --request POST "$LAGO_URL/api/v1/plans" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "plan": {
        "name": "Notion Team plan",
        "code": "notion_team_plan",
        "interval": "monthly",
        "amount_cents": 0,
        "amount_currency": "USD",
        "trial_period": 0.0,
        "pay_in_advance": false,
        "bill_charges_monthly": null,
        "charges": [
          {
            "billable_metric_id": "d4f8056c-6321-4a82-9cd7-1e08313764f4",
            "billable_metric_code": "users",
            "charge_model": "standard",
            "invoiceable": true,
            "pay_in_advance": false,
            "prorated": true,
            "min_amount_cents": 0,
            "properties": {
              "amount": "10"
            },
            "filters": [],
            "taxes": []
          }
        ],
      }
    }
    ```
  </Tab>
</Tabs>

If the same user is removed before the end of the month, Lago will automatically recalculate the number of **billable days** (i.e. the number of billing units).

## Step 3: Offer credits to your customers

Now that our pricing is ready, we can set up our credit system. Notion customers earn credits when they use the app across different devices and try out new features.

<Frame caption="Notion 'Earn credit' tab">
  <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/notion-credits.png" />
</Frame>

<Tabs>
  <Tab title="Dashboard">
    In the **'Wallets' tab** of the customer view, we can create a new wallet, which will allow us to grant credits to our customer. If later they complete additional tasks, we'll be able to top up their wallet with free credits.

    <Frame caption="How to create a new wallet">
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/notion-wallet-creation.png" />
    </Frame>

    Credits are automatically deducted from the customer's next invoice(s).
  </Tab>

  <Tab title="API">
    ```bash
    # Create a wallet
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"
    curl --location --request POST "$LAGO_URL/api/v1/wallets" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "wallet": {
        "name": "Notion Credits",
        "rate_amount": "1.0",
        "paid_credits": "0.0",
        "granted_credits": "10.0",
        "currency": "USD",
        "expiration_at": null,
        "expiration_date": null,
        "recurring_transaction_rules": []
      }
    }
    ```
  </Tab>
</Tabs>

## Wrap-up

For software companies like Notion, implementing a 'fair' per-user pricing model is a good way to **increase transparency and customer satisfaction**.
With Lago, you can create your own persistent metrics to adapt this template to your products and services.

Give it a try, click [here](https://www.getlago.com/get-started) to get started!


# Clone Mistral pricing

Replicate Mistral's per-token pricing model with Lago.

In this article, you will learn how Mistral is using Lago to build a billing system based on AI tokens.
This template is suitable for Large Language Model (LLM) and Generative AI companies whose pricing can vary based on the application or model used.

## Summary

<Steps>
  <Step title="Aggregate usage with filters">
    Use single metric to meter tokens with different filters.
    [(More here)](#step-1-aggregate-usage-with-filters).
  </Step>

  <Step title="Set up a per-token pricing">
    Create a plan to price packages of tokens used.
    [(More here)](#step-2-set-up-a-per-token-pricing).
  </Step>

  <Step title="Prepay usage with credits">
    Prepay usage with credits and set top-up rules in real-time.
    [(More here)](#step-3-prepay-usage-with-credits).
  </Step>

  <Step title="Ingest usage in real-time">
    Retrieve consumed tokens in real-time.
    [(More here)](#step-4-ingest-usage-in-real-time).
  </Step>
</Steps>

## Pricing structure

For Mistral, pricing depends on the language model used. Here are several price points they offer:
Prices are per 1M tokens used. You can think of tokens as pieces of words (learn more [here](https://mistral.ai/technology/#models))."

### Open source models pricing

| Models             | Input              | Output             |
| ------------------ | ------------------ | ------------------ |
| open-mistral-7b    | \$0.25 / 1M tokens | \$0.25 / 1M tokens |
| open-mixtral-8x7b  | \$0.7 / 1M tokens  | \$0.7 / 1M tokens  |
| open-mixtral-8x22b | \$2 / 1M tokens    | \$6 / 1M tokens    |

### Optimized models pricing

| Models         | Input             | Output            |
| -------------- | ----------------- | ----------------- |
| mistral-small  | \$1 / 1M tokens   | \$3 / 1M tokens   |
| mistral-medium | \$2.7 / 1M tokens | \$8.1 / 1M tokens |
| mistral-large  | \$4 / 1M tokens   | \$12 / 1M tokens  |

## Step 1: Aggregate usage with filters

Lago monitors usage by converting events into billable metrics. To illustrate how this works, we are going to take the Optimized models (Mistral small, medium or large models) as an example.
Mistral pricing includes a single metric based on the total number of tokens processed on the platform.

<Tabs>
  <Tab title="Dashboard">
    To create the corresponding metric, we use the `sum` aggregation type, which will allow us to record usage and calculate the total number of tokens used. In this case, the aggregation type is **metered**. This means that usage is reset to 0 at the beginning of the next billing cycle.
    For this metric, there are two dimensions that will impact the price of the token:

    *   **Model:** mistral-small, mistral-medium or mistral-large; and
    *   **Type**: Input data or Output data.

    Therefore, we propose integrating these two dimensions into our metric as **filters**:

    *   **Filter #1:** Distinguishes between various models utilized; and
    *   **Filter #2:** Separates input and output types.
        By implementing these filters, we can assign distinct prices to a single metric, based on events' properties.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/qZLRsVOk-MY?si=iC4gD3ZG3U17L_b7&start=40" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Create a metric with filters
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"

        curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
        "billable_metric": {
            "name": "Optimized models",
            "code": "optimized_models",
            "description": "",
            "aggregation_type": "sum_agg",
            "weighted_interval": null,
            "recurring": false,
            "field_name": "total",
            "filters": [
                {
                  "key": "model",
                  "values": ["mistral_small", "mistral_medium", "mistral_large]
                },
                {
                  "key": "type",
                  "values": ["input", "output"]
                }
            ]
        }
    }'
    ```
  </Tab>
</Tabs>

## Step 2: Set up a per token pricing

When creating a new plan, the first step is to define the plan model, including billing frequency and subscription fee. Mistral pricing is ‘pay-as-you-go’, which means that there’s no subscription fee (i.e. customers only pay for what they use).

<Tabs>
  <Tab title="Dashboard">
    Our plan includes the ‘per 1M tokens’ charge, for which we choose the `package` pricing model.
    As we have defined 2 filters (models and type), we can set a specific price for each Model/Type combination.
    We can apply the same method to create plans for other models, like *Embeddings* or *Open source models*. Our plan is ready to be used, now let’s see how Lago handles billing by ingesting usage.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/qZLRsVOk-MY?si=xZN856Dod8YNRoob&start=176" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Pricing per million tokens
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request POST "$LAGO_URL/api/v1/plans" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "plan": {
            "name": "Pay as you go",
            "invoice_display_name": null,
            "code": "payg",
            "interval": "monthly",
            "description": "",
            "amount_cents": 0,
            "amount_currency": "USD",
            "trial_period": 0.0,
            "pay_in_advance": false,
            "charges": [
              {
                "billable_metric_id": "488459e1-f971-42b9-9a6b-63f0719f9006",
                "invoice_display_name": null,
                "billable_metric_code": "optimized_models",
                "charge_model": "package",
                "invoiceable": true,
                "pay_in_advance": false,
                "prorated": false,
                "min_amount_cents": 0,
                "properties": {
                  "amount": "0",
                  "free_units": 0,
                  "package_size": 1
                },
                "filters": [
                    {
                        "invoice_display_name": null,
                        "properties": {
                            "amount": "1",
                            "free_units": 0,
                            "package_size": 1000000
                        },
                        "values": {
                            "models": ["mistral-small"],
                            "type": ["input"]
                        }
                    },
                    {
                        "invoice_display_name": null,
                        "properties": {
                            "amount": "3",
                            "free_units": 0,
                            "package_size": 1000000
                        },
                        "values": {
                            "models": ["mistral-small"],
                            "type": ["output"]
                        }
                    },
                    {
                        "invoice_display_name": null,
                        "properties": {
                            "amount": "2.7",
                            "free_units": 0,
                            "package_size": 1000000
                        },
                        "values": {
                            "models": ["mistral-medium"],
                            "type": ["input"]
                        }
                    },
                    {
                        "invoice_display_name": null,
                        "properties": {
                            "amount": "8.1",
                            "free_units": 0,
                            "package_size": 1000000
                        },
                        "values": {
                            "models": ["mistral-medium"],
                            "type": ["output"]
                        }
                    }
                ],
                "taxes": []
              }
            ],
            "taxes": []
        }
    }
    '

    ```
  </Tab>
</Tabs>

## Step 3: Prepay usage with credits

<Tabs>
  <Tab title="Dashboard">
    Mistral, following industry practice, employs prepaid credits to facilitate payment collection in advance. Users prepay for credits corresponding to their anticipated model usage.
    Moreover, Lago actively monitors credit utilization in real-time and offers customizable top-up rules based on predefined thresholds or time periods.

    From the user interface:

    *   Create a new wallet for prepaid credits;
    *   Set a ratio (e.g., 1 credit equals \$1);
    *   Specify the number of credits for offer or purchase; and
    *   Configure recurring top-up rules based on real-time usage (threshold or interval top-ups).

    <iframe width="560" height="315" src="https://www.youtube.com/embed/qZLRsVOk-MY?si=mIXQiUbzDn35UYcX&start=318" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Prepay usage with credits
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"

        curl --location --request POST "$LAGO_URL/api/v1/wallets" \
          --header "Authorization: Bearer $API_KEY" \
          --header 'Content-Type: application/json' \
          --data-raw '{
            "wallet": {
              "name": "Prepaid",
              "rate_amount": "1.5",
              "paid_credits": "20.0",
              "granted_credits": "10.0",
              "currency": "USD",
              "expiration_at": "2022-07-07",
              "external_customer_id": "hooli_1234"
            }
          }'
    ```
  </Tab>
</Tabs>

## Step 4: Ingest usage in real-time

<Tabs>
  <Tab title="Dashboard">
    Mistral records the token usage based on the model used. These activities are converted into events that are pushed to Lago.
    Let’s take the Optimized Models as an example:
    Lago will group events according to:

    *   The billable metric code;
    *   The model; and
    *   The type.

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/mistral-tokens-usage.png" />
    </Frame>

    For each charge, the billing system will then automatically calculate the total token usage and corresponding price.
    This breakdown will be displayed in the ‘Usage’ tab of the user interface and on the invoice sent to the customer.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/qZLRsVOk-MY?si=eBR35kg5UCuV0bmE&start=430" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Ingest tokens usage via events
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/events" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "event": {
          "transaction_id": "{{$randomUUID}}",
          "code": "optimized_models",
          "external_customer_id": "hooli_123",
          "properties": {
              "tokens": 2000000,
              "models": "mistral-small",
              "type": "output"
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## Wrap-up

Per-token pricing offers flexibility and visibility, and allows LLM and Generative AI companies like Mistral to attract more customers.
With Lago, you can create your own metric dimensions to adapt this template to your products and services.

Give it a try, click [here](https://www.getlago.com/get-started) to get started!


# Clone OpenAI pricing

Replicate OpenAI's per-token pricing model with Lago.

In this article, you will learn how to build a billing system with Lago based on tokens.
This template is suitable for Large Language Model (LLM) and Generative AI companies whose pricing can vary based on the application or model used.

## Summary

<Steps>
  <Step title="Aggregate usage with filters">
    Use single metric to meter tokens with different filters.
    [(More here)](#step-1-aggregate-usage-with-filters).
  </Step>

  <Step title="Set up a per token pricing">
    Create a plan to price packages of tokens used.
    [(More here)](#step-2-set-up-a-per-token-pricing).
  </Step>

  <Step title="Ingest usage in real-time">
    Retrieve consumed tokens in real-time.
    [(More here)](#step-3-ingest-usage-in-real-time).
  </Step>
</Steps>

## Pricing structure

For OpenAI, pricing depends on the language model used. Here are several price points they offer:
*"Prices are per 1,000 tokens. You can think of tokens as pieces of words, where 1,000 tokens is about 750 words (learn more [here](https://platform.openai.com/tokenizer))."*

### GPT-3.5 Turbo pricing

| Model       | Input                   | Output                 |
| ----------- | ----------------------- | ---------------------- |
| 4K context  | \$0.0015 / 1,000 tokens | \$0.002 / 1,000 tokens |
| 16K context | \$0.003 / 1,000 tokens  | \$0.005 / 1,000 tokens |

### GPT-4 pricing

| Model       | Input                 | Output                |
| ----------- | --------------------- | --------------------- |
| 8K context  | \$0.03 / 1,000 tokens | \$0.06 / 1,000 tokens |
| 32K context | \$0.06 / 1,000 tokens | \$0.12 / 1,000 tokens |

## Step 1: Aggregate usage with filters

Lago monitors usage by converting events into billable metrics. To illustrate how this works, we are going to take GPT-4 as an example. OpenAI’s GPT-4 pricing includes a single metric based on the total number of tokens processed on the platform.

<Tabs>
  <Tab title="Dashboard">
    To create the corresponding metric, we use the `sum` aggregation type, which will allow us to record usage and calculate the total number of tokens used. In this case, the aggregation type is **metered**. This means that usage is reset to 0 at the beginning of the next billing cycle.
    For this metric, there are two dimensions that will impact the price of the token:

    *   **Model:** 8K context or 32K context; and
    *   **Type**: Input data or Output data.

    Therefore, we propose integrating these two dimensions into our metric as **filters**:

    *   **Filter #1:** Distinguishes between various models utilized; and
    *   **Filter #2:** Separates input and output types.
        By implementing these filters, we can assign distinct prices to a single metric, based on events' properties.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/ulLpAn8_P9o?si=18NXjL8pITlrVuZ7&start=35" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Create a metric with filters
        LAGO_URL="https://api.getlago.com"
        API_KEY="__YOUR_API_KEY__"

        curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
        --header "Authorization: Bearer $API_KEY" \
        --header 'Content-Type: application/json' \
        --data-raw '{
        "billable_metric": {
            "name": "Tokens",
            "code": "tokens",
            "description": "",
            "aggregation_type": "sum_agg",
            "weighted_interval": null,
            "recurring": false,
            "field_name": "total",
            "filters": [
                {
                  "key": "model",
                  "values": [
                      "32k",
                      "8k"
                  ]
                },
                {
                  "key": "type",
                  "values": [
                      "input",
                      "output"
                  ]
                }
            ]
        }
    }'
    ```
  </Tab>
</Tabs>

## Step 2: Set up a per token pricing

When creating a new plan, the first step is to define the plan model, including billing frequency and subscription fee. OpenAI pricing is ‘pay-as-you-go’, which means that there’s no subscription fee (i.e. customers only pay for what they use).

<Tabs>
  <Tab title="Dashboard">
    Here is how to set the monthly plan for GPT-4. Our plan includes the ‘per 1,000 tokens’ charge, for which we choose the `package` pricing model.
    As we have defined 2 filters (models and type), we can set a specific price for each Model/Type combination.
    We can apply the same method to create plans for GPT-3.5 Turbo. Our plan is ready to be used, now let’s see how Lago handles billing by ingesting usage.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/ulLpAn8_P9o?si=zlSmr__6QWIjhD2R&start=152" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Pricing per tokens
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request POST "$LAGO_URL/api/v1/plans" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "plan": {
            "name": "Pay as you go",
            "invoice_display_name": null,
            "code": "payg",
            "interval": "monthly",
            "description": "",
            "amount_cents": 0,
            "amount_currency": "USD",
            "trial_period": 0.0,
            "pay_in_advance": false,
            "charges": [
              {
                "billable_metric_id": "488459e1-f971-42b9-9a6b-63f0719f9006",
                "invoice_display_name": null,
                "billable_metric_code": "tokens",
                "charge_model": "package",
                "invoiceable": true,
                "pay_in_advance": false,
                "prorated": false,
                "min_amount_cents": 0,
                "properties": {
                  "amount": "0",
                  "free_units": 0,
                  "package_size": 1
                },
                "filters": [
                  {
                    "invoice_display_name": null,
                    "properties": {
                        "amount": "0.03",
                        "free_units": 0,
                        "package_size": 1000
                    },
                    "values": {
                        "model": ["8k"],
                        "type": ["input"]
                    }
                  },
                  {
                    "invoice_display_name": null,
                    "properties": {
                        "amount": "0.06",
                        "free_units": 0,
                        "package_size": 1000
                    },
                    "values": {
                        "model": ["8k"],
                        "type": ["output"]
                    }
                  },
                  {
                    "invoice_display_name": null,
                    "properties": {
                        "amount": "0.06",
                        "free_units": 0,
                        "package_size": 1000
                    },
                    "values": {
                        "model": ["32k"],
                        "type": ["input"]
                    }
                  },
                  {
                      "invoice_display_name": null,
                      "properties": {
                          "amount": "0.12",
                          "free_units": 0,
                          "package_size": 1000
                      },
                      "values": {
                          "model": ["32k"],
                          "type": ["output"]
                      }
                  }
                ],
                "taxes": []
              }
            ],
            "taxes": []
        }
    }
    '

    ```
  </Tab>
</Tabs>

## Step 3: Ingest usage in real-time

<Tabs>
  <Tab title="Dashboard">
    OpenAI records the token usage, the number of images, and the usage of transcribing speech into text. These activities are converted into events that are pushed to Lago.
    Let’s take GPT-4 as an example:
    Lago will group events according to:

    *   The billable metric code;
    *   The model; and
    *   The type.

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/tokens-usage.png" />
    </Frame>

    For each charge, the billing system will then automatically calculate the total token usage and corresponding price.
    This breakdown will be displayed in the ‘Usage’ tab of the user interface and on the invoice sent to the customer.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/ulLpAn8_P9o?si=XjYk1hi7sdShmeKv&start=310" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Ingest tokens usage via events
      LAGO_URL="https://api.getlago.com"
      API_KEY="__YOUR_API_KEY__"

      curl --location --request POST "$LAGO_URL/api/v1/events" \
      --header "Authorization: Bearer $API_KEY" \
      --header 'Content-Type: application/json' \
      --data-raw '{
        "event": {
          "transaction_id": "{{$randomUUID}}",
          "code": "tokens",
          "external_customer_id": "__YOUR_CUSTOMER_ID__",
          "external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
          "properties": {
            "total": 5000,
            "model": "8k",
            "type": "input"
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## Wrap-up

Per-token pricing offers flexibility and visibility, and allows LLM and Generative AI companies like OpenAI to attract more customers.
With Lago, you can create your own metric dimensions to adapt this template to your products and services.

Give it a try, click [here](https://www.getlago.com/get-started) to get started!


# Clone Stripe pricing

Replicate Stripe's per-transaction pricing model with Lago.

Implement a per-transaction pricing model like Stripe, the leading payments infrastructure company, including fees based on the total amount and number of transactions.

In this article, you will learn how to build a per-transaction billing system with Lago, where a single event can trigger instant charges.
This template is suitable for companies whose pricing depends on transactions, such as fintechs and marketplaces that deduct their fees from their customers' revenue.

## Summary

<Steps>
  <Step title="Record a transaction usage with billable metrics">
    Ensure transactions are promptly recorded as they occur.
    [(More here)](#step-1-create-billable-metrics-for-transaction).
  </Step>

  <Step title="Price transactions with in advance charges">
    Establish a price per transaction, incorporating upfront charges and specifying fixed fees, as well as minimum and maximum spending thresholds per transaction.
    [(More here)](##step-2-price-transaction-with-in-advance-charges).
  </Step>

  <Step title="Ingest transactions in real-time">
    Ingest each new transaction in real-time.
    [(More here)](#step-3-ingest-transactions-in-real-time).
  </Step>

  <Step title="Estimate a fee for a future transaction">
    Ingest each new transaction in real-time.
    [(More here)](#step-4-estimate-fees-for-future-transactions).
  </Step>
</Steps>

## Pricing structure

Stripe offers 'pay-as-you-go' pricing based on successful card charges processed via its platform.
Stripe's API includes many payment options. Rates and fixed fees per transaction vary depending on the payment method.

| Payment Method                  | Percentage Charge (based on transaction amount) | Fixed Fee (per transaction) |
| ------------------------------- | ----------------------------------------------- | --------------------------- |
| Card payments (online)          | 2.9%                                            | \$0.30                      |
| Card payments (in-person)       | 2.7%                                            | \$0.05                      |
| Wallets (Apple Pay, Alipay)     | 2.9%                                            | \$0.30                      |
| Pre-authorised debits in Canada | 1.0%                                            | \$0.30                      |
| SEPA Direct Debit               | 0.8%                                            | \$0.30                      |
| SOFORT                          | 1.4%                                            | \$0.30                      |

As Stripe supports more 20 payment methods in the US and most of them share the same charge model, we will focus on online card payments.

Here's how you can replicate this pricing with our billing solution.

## Step 1: Create billable metrics for transaction

<Tabs>
  <Tab title="Dashboard">
    Lago monitors consumption by converting events into billable metrics. For Stripe's per-transaction pricing, we can create a billable metric for each payment method.

    Using the `sum` aggregation type, we create a billable metric that will allow us to record transactions. In this case, the aggregation type is `metered`. It means the aggregated amount is reset to 0 at the beginning of the next billing cycle.

    When a successful card charge is processed via the platform, our backend system will generate an `online_payments` event, including the transaction amount.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/SBc7eB3T0rE?si=EAmRNU92Bgrh7w_B&start=62" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Create a metric for each transaction
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"

    curl --location --request POST "$LAGO_URL/api/v1/billable_metrics" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "billable_metric": {
        "name": "SEPA",
        "code": "sepa",
        "description": "",
        "aggregation_type": "sum_agg",
        "weighted_interval": null,
        "recurring": false,
        "field_name": "amount",
        "filters": []
      }
    }'
    ```
  </Tab>
</Tabs>

## Step 2: Price transaction with in advance charges

When creating a new plan, the first thing to do is to define the plan model, including billing frequency and subscription fee. Here we can select the monthly plan interval. As we are implementing a 'pay-as-you-go' pricing model, there is no subscription fee.

<Tabs>
  <Tab title="Dashboard">
    We want our customers to pay for their use of the payments platform, so we add charges to our plan. Each charge is associated with a billable metric (i.e. one charge per payment method in this case) and has its own pricing structure. In order to replicate Stripe’s pricing, we select the percentage metered charge model then choose pay charge in-advance (`pay_in_advance` is `true`).
    Additionally, the option to generate invoice for each event should be turned off as Stripe doesn't bill customers for individual transactions (`invoiceable` is `false`).

    The percentage charge model allows us to combine a percentage charge **based on the amount of the transaction and a fixed fee**.

    If you want to charge your user on this usage on a monthly basis, you can set up the same way using the Percentage charge model and charge it in arrears.

    If we wanted to go even further, we could define free units. For instance, we could:

    *   Offer the first three transactions; or
    *   Offer the first \$1,000; or
    *   Create a model where the first three transactions or first \$1,000 would be free; or
    *   Specify minimum and maximum transaction spending limits. For instance, ensure a minimum fee of \$2 per transaction, even if the result falls below this threshold.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/SBc7eB3T0rE?si=sTjrPPQKqny72b1I&start=62" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Pricing percentage fees in-advance
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"
    curl --location --request POST "$LAGO_URL/api/v1/plans" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "plan": {
          "name": "Basic",
          "code": "basic",
          "interval": "monthly",
          "amount_cents": 0,
          "amount_currency": "USD",
          "pay_in_advance": false,
          "charges": [
            {
              "billable_metric_id": "32c2e174-2c7c-41e7-983b-3018d08e02c1",
              "billable_metric_code": "sepa",
              "charge_model": "percentage",
              "invoiceable": false,
              "pay_in_advance": true,
              "prorated": false,
              "min_amount_cents": 0,
              "properties": {
                "rate": "0.8",
                "fixed_amount": "0.30"
              },
              "filters": [],
              "taxes": []
            }
          ],
          "taxes": []
      }
    }'
    ```
  </Tab>
</Tabs>

## Step 3: Ingest transactions in real-time

<Tabs>
  <Tab title="Dashboard">
    Stripe records each transaction based on their type, and charge it instantly. These activities are converted into events that are pushed to Lago.

    <Frame>
      <img src="https://mintlify.s3-us-west-1.amazonaws.com/lago-docs/templates/images/mistral-tokens-usage.png" />
    </Frame>

    For each transaction, the billing system will then automatically calculate the total amount to charge to the end user.
    This breakdown will be displayed in the 'Usage' tab of the user interface and on the invoice sent to the customer.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/SBc7eB3T0rE?si=ZYTvyUDiVYhGC6-5" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Ingest event for each transaction
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"
    curl --location --request POST "$LAGO_URL/api/v1/events" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "event": {
        "transaction_id": "{{$randomUUID}}",
        "code": "sepa",
        "external_customer_id": "hooli_1234",
        "properties": {
          "amount": 200
        }
      }
    }'
    ```
  </Tab>
</Tabs>

## Step 4: Estimate fees for future transactions

<Tabs>
  <Tab title="Dashboard">
    Stripe records each transaction based on their type, and charge it instantly. These activities are converted into events that are pushed to Lago.

    For each transaction, the billing system will then automatically calculate the total amount to charge to the end user.
    This breakdown will be displayed in the 'Usage' tab of the user interface and on the invoice sent to the customer.

    <iframe width="560" height="315" src="https://www.youtube.com/embed/SBc7eB3T0rE?si=DrGUzrrVHhh-7tZS&start=412" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />
  </Tab>

  <Tab title="API">
    ```bash Estimate a fee for a future transaction
    LAGO_URL="https://api.getlago.com"
    API_KEY="__YOUR_API_KEY__"
    curl --location --request POST "$LAGO_URL/api/v1/events/estimate_fees" \
    --header "Authorization: Bearer $API_KEY" \
    --header 'Content-Type: application/json' \
    --data-raw '{
      "event": {
          "external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
          "code": "__BILLABLE_METRIC_CODE__",
          "properties": {
            "amount": 1200,
          }
        }
      }'
    ```
  </Tab>
</Tabs>

## Wrap-up

For fintech companies like Stripe, implementing a per-transaction pricing model is a good way to **increase revenue as customers grow and capture value everytime a transaction is processed**.
With Lago, you can create your own billable metrics and use the percentage charge model paid instantly to adapt this template to your products and services.

Give it a try, click [here](https://www.getlago.com/get-started) to get started!