Skip to main content

Messages

Here is the list of webhook messages sent by Lago.

Draft invoice created
Sent when a new invoice is in draft.
{
"webhook_type": "invoice.drafted",
"object_type": "invoice",
"invoice": {
"lago_id": "10pb140c-0e7a-44dc-bdff-b683d0770et9",
"sequential_id": 2,
"number": "LAG-1234-001-002",
"issuing_date": "2023-01-22",
"invoice_type": "subscription",
"status": "draft",
"payment_status": "pending",
"amount_cents": 5500,
"amount_currency": "USD",
"vat_amount_cents": 0,
"vat_amount_currency": "USD",
"credit_amount_cents": 0,
"credit_amount_currency": "USD",
"total_amount_cents": 5500,
"total_amount_currency": "USD",
"file_url": null,
"legacy": false,
"customer": {
"lago_id": "578df9d1-a5b5-abc4-b1cd-cc123159cdj3",
"external_id": "customer_1234",
"name": "Helen Ross",
"sequential_id": 26,
"slug": "LAG-X575-026",
"created_at": "2023-01-11T06:59:44Z",
"country": null,
"address_line1": null,
"address_line2": null,
"state": null,
"zipcode": null,
"email": null,
"city": null,
"url": null,
"phone": null,
"logo_url": null,
"legal_name": null,
"legal_number": null,
"currency": "USD",
"timezone": null,
"applicable_timezone": "Europe/Paris",
"billing_configuration": {
"invoice_grace_period": null,
"payment_provider": null,
"vat_rate": null
}
},
"subscriptions": [
{
"lago_id": "00911bba-d074-1234-abcd-00d4e57746mm",
"external_id": "07cc066d-1234-5678-xyzw-e42ea21e6307",
"lago_customer_id": "578df9d1-a5b5-abc4-b1cd-cc123159cdj3",
"external_customer_id": "customer_1234",
"name": "",
"plan_code": "corporate",
"status": "active",
"billing_time": "anniversary",
"subscription_at": "2023-01-17T15:44:16Z",
"started_at": "2023-01-17T15:44:16Z",
"terminated_at": null,
"canceled_at": null,
"created_at": "2023-01-17T15:44:39Z",
"previous_plan_code": null,
"next_plan_code": null,
"downgrade_plan_date": null,
"subscription_date": "2023-01-17"
}
],
"fees": [
{
"lago_id": "12345678-ebea-47de-ghjk-bbbfd42755f3",
"lago_group_id": null,
"item": {
"type": "subscription",
"code": "corporate",
"name": "Corporate"
},
"amount_cents": 5500,
"amount_currency": "USD",
"vat_amount_cents": 0,
"vat_amount_currency": "USD",
"units": "1.0",
"events_count": null
}
],
"credits": []
}
}
AttributesDescription
invoice     JSON     Not nullableInvoice object
Finalized invoice created
Sent when an invoice is finalized.

This will allow your application to proceed with the billing.

{
"webhook_type": "invoice.created",
"object_type": "invoice",
"invoice": {
"lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"sequential_id": 2,
"number": "LAG-1234-001-002",
"charges_from_date": "2022-04-01",
"issuing_date": "",
"amount_cents": 100,
"amount_currency": "EUR",
"vat_amount_cents": 20,
"vat_amount_currency": "EUR",
"total_amount_cents": 120,
"total_amount_currency": "EUR",
"file_url": "https://getlago.com/invoice/file",
"customer": {
"lago_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
"sequential_id": 1,
"slug": "LAG-1234-001",
"external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"address_line1": "5230 Penfield Ave",
"address_line2": null,
"city": "Woodland Hills",
"country": "US",
"created_at": "2022-04-29T08:59:51Z",
"email": "dinesh@piedpiper.test",
"legal_name": "Coleman-Blair",
"legal_number": "49-008-2965",
"logo_url": "http://hooli.com/logo.png",
"name": "Gavin Belson",
"phone": "1-171-883-3711 x245",
"state": "CA",
"url": "http://hooli.com",
"vat_rate": 20.0,
"zipcode": "91364"
},
"subscriptions": [
{
"lago_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
"external_id": "susbcription_external_id",
"lago_customer_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
"external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"canceled_at": "2022-04-29T08:59:51Z",
"created_at": "2022-04-29T08:59:51Z",
"plan_code": "new_code",
"started_at": "2022-04-29T08:59:51Z",
"status": "active",
"terminated_at": null
}
],
"fees": [
{
"lago_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
"item": {
"type": "subscription",
"code": "plan_code",
"name": "Plan"
},
"amount_cents": 100,
"amount_currency": "EUR",
"vat_amount_cents": 20,
"vat_amount_currency": "EUR",
"units": "0.32",
"events_count": 23
}
],
"credits": [
{
"lago_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
"item": {
"lago_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
"type": "coupon",
"code": "coupon_code",
"name": "Coupon"
},
"amount_cents": 100,
"amount_currency": "EUR"
}
]
}
}
AttributesDescription
invoice     JSON     Not nullableInvoice object
PDF invoice generated
Sent when the PDF file has been generated for a customer invoice.

This will allow your application to retrieve the PDF invoice.

{
"webhook_type": "invoice.generated",
"object_type": "invoice",
"invoice": {
"lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"sequential_id": 2,
"number": "LAG-1234-001-002",
"from_date": "2022-04-01",
"to_date": "2022-04-30",
"charges_from_date": "2022-04-01",
"issuing_date": "",
"amount_cents": 100,
"amount_currency": "EUR",
"vat_amount_cents": 20,
"vat_amount_currency": "EUR",
"total_amount_cents": 120,
"total_amount_currency": "EUR",
"file_url": "https://getlago.com/invoice/file",
}
}
AttributesDescription
invoice     JSON     Not nullableInvoice object
Add-on added
Sent when an add-on has been applied to customer. The invoice is created immediately after the add-on is assigned to a customer.

You can use this information to generate a PDF invoice or collect the payment.

{
"webhook_type": "invoice.add_on_added",
"object_type": "invoice",
"invoice": {
"lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"sequential_id": 2,
"issuing_date": "2022-04-30",
"amount_cents": 100,
"amount_currency": "EUR",
"vat_amount_cents": 20,
"vat_amount_currency": "EUR",
"total_amount_cents": 120,
"total_amount_currency": "EUR",
"customer": {
"lago_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
"external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"address_line1": "5230 Penfield Ave",
"address_line2": null,
"city": "Woodland Hills",
"country": "US",
"created_at": "2022-04-29T08:59:51Z",
"email": "dinesh@piedpiper.test",
"legal_name": "Coleman-Blair",
"legal_number": "49-008-2965",
"logo_url": "http://hooli.com/logo.png",
"name": "Gavin Belson",
"phone": "1-171-883-3711 x245",
"state": "CA",
"url": "http://hooli.com",
"vat_rate": 20.0,
"zipcode": "91364"
},
"subscription": {
"lago_id": "b7ab2926-1de8-4428-9bcd-779314ac129b",
"external_id": "susbcription_external_id",
"lago_customer_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
"external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"canceled_at": "2022-04-29T08:59:51Z",
"created_at": "2022-04-29T08:59:51Z",
"plan_code": "new_code",
"started_at": "2022-04-29T08:59:51Z",
"status": "active",
"terminated_at": null
},
"fees": [
{
"item": {
"type": "add_on",
"code": "add_on_code",
"name": "add_on_name"
},
"amount_cents": 100,
"amount_currency": "EUR",
"vat_amount_cents": 20,
"vat_amount_currency": "EUR",
"units": "1",
"events_count": 23
}
]
}
}
AttributesDescription
invoice     JSON     Not nullableInvoice object
Prepaid credits added
Sent when prepaid credits have been added to the customer's wallet.

You can use this information to generate a PDF invoice or collect the payment.

{
"webhook_type": "invoice.paid_credit_added",
"object_type": "invoice",
"invoice": {
"lago_id": "dd3f587c-1122-4fc1-a8dd-dfghj0d98765",
"sequential_id": 7,
"number": "LAG-C875-031-007",
"issuing_date": "2023-01-18",
"invoice_type": "credit",
"status": "finalized",
"payment_status": "pending",
"amount_cents": 5000,
"amount_currency": "USD",
"vat_amount_cents": 0,
"vat_amount_currency": "USD",
"credit_amount_cents": 0,
"credit_amount_currency": "USD",
"total_amount_cents": 5000,
"total_amount_currency": "USD",
"file_url": null,
"legacy": false,
"customer": {
"lago_id": "12345678-qsdf-vbnm-898f-f0d29a8e0eea",
"external_id": "seb_1234",
"name": "Sebastian Molde",
"sequential_id": 31,
"slug": "LAG-C875-031",
"created_at": "2023-01-17T13:43:53Z",
"country": null,
"address_line1": null,
"address_line2": null,
"state": null,
"zipcode": null,
"email": null,
"city": null,
"url": null,
"phone": null,
"logo_url": null,
"legal_name": null,
"legal_number": null,
"currency": "USD",
"timezone": null,
"applicable_timezone": "Europe/Paris",
"billing_configuration": {
"invoice_grace_period": null,
"payment_provider": null,
"vat_rate": null
}
},
"fees": [
{
"lago_id": "600a3709-erty-8765-3214-e4ca436fe6b6",
"lago_group_id": null,
"item": {
"type": "credit",
"code": "credit",
"name": "credit"
},
"amount_cents": 5000,
"amount_currency": "USD",
"vat_amount_cents": 0,
"vat_amount_currency": "USD",
"units": "1.0",
"events_count": null
}
]
}
}
AttributesDescription
invoice     JSON     Not nullableInvoice object
Credit note created
Sent when a new credit note has been issued for a customer.

This will allow your application to proceed with the refund.

{
"webhook_type": "credit_note.created",
"object_type": "credit_note",
"credit_note": {
"lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"sequential_id": 2,
"number": "LAG-1234-CN2",
"lago_invoice_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"invoice_number": "LAG-1234",
"issuing_date": "2022-12-06",
"credit_status": "available",
"refund_status": "pending",
"reason": "other",
"description": "Free text",
"total_amount_cents": 120,
"total_amount_currency": "EUR",
"credit_amount_cents": 100,
"credit_amount_currency": "EUR",
"refund_amount_cents": 0,
"refund_amount_currency": "EUR",
"balance_amount_cents": 100,
"balance_amount_currency": "EUR",
"vat_amount_cents": 20,
"vat_amount_currency": "EUR",
"sub_total_vat_excluded_amount_cents": 100,
"sub_total_vat_excluded_amount_currency": "EUR",
"created_at": "2022-10-06 09:52:00",
"updated_at": "2022-10-06 09:52:00",
"file_url": "https://getlago.com/credit_note/file",
"items": [
{
"lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"amount_cents": 100,
"amount_currency": "EUR",
"fee": {
"lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"item": {
"type": "charge",
"code": "user_seats",
"name": "User Seats"
},
"amount_cents": 100,
"amount_currency": "",
"vat_amount_cents": 20,
"vat_amount_currency": "EUR",
"units": 12.6,
"events_count": 10
}
}
]
}
}
AttributesDescription
credit_note     JSON     Not nullableCredit note object
PDF credit note generated
Sent when the PDF file has been generated for a credit note.

This will allow your application to retrieve the PDF credit note.

{
"webhook_type": "credit_note.generated",
"object_type": "credit_note",
"credit_note": {
"lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"sequential_id": 2,
"number": "LAG-1234-CN2",
"lago_invoice_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"invoice_number": "LAG-1234",
"issuing_date": "2022-12-06",
"credit_status": "available",
"refund_status": "pending",
"reason": "other",
"description": "Free text",
"total_amount_cents": 120,
"total_amount_currency": "EUR",
"credit_amount_cents": 100,
"credit_amount_currency": "EUR",
"refund_amount_cents": 0,
"refund_amount_currency": "EUR",
"balance_amount_cents": 100,
"balance_amount_currency": "EUR",
"vat_amount_cents": 20,
"vat_amount_currency": "EUR",
"sub_total_vat_excluded_amount_cents": 100,
"sub_total_vat_excluded_amount_currency": "EUR",
"created_at": "2022-10-06 09:52:00",
"updated_at": "2022-10-06 09:52:00",
"file_url": "https://getlago.com/credit_note/file",
"items": [
{
"lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"amount_cents": 100,
"amount_currency": "EUR",
"fee": {
"lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"item": {
"type": "charge",
"code": "user_seats",
"name": "User Seats"
},
"amount_cents": 100,
"amount_currency": "",
"vat_amount_cents": 20,
"vat_amount_currency": "EUR",
"units": 12.6,
"events_count": 10
}
}
]
}
}
AttributesDescription
credit_note     JSON     Not nullableCredit note object
Payment provider created
This webhook is 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.

{
"webhook_type": "customer.payment_provider_created",
"object_type": "customer",
"customer": {
"lago_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
"external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"address_line1": "5230 Penfield Ave",
"address_line2": null,
"city": "Woodland Hills",
"country": "US",
"created_at": "2022-04-29T08:59:51Z",
"email": "dinesh@piedpiper.test",
"legal_name": "Coleman-Blair",
"legal_number": "49-008-2965",
"logo_url": "http://hooli.com/logo.png",
"name": "Gavin Belson",
"phone": "1-171-883-3711 x245",
"state": "CA",
"url": "http://hooli.com",
"vat_rate": 12.5,
"zipcode": "91364",
"billing_configuration": {
"payment_provider": "stripe",
"provider_customer_id": "cus_12345"
}
}
}
AttributesDescription
customer     JSON     Not nullableCustomer object
Payment provider error
This webhook is sent when there is an error related to the creation of a customer in the payment provider's application.

You should review the customer's data.

{
"webhook_type": "invoice.payment_failure",
"object_type": "payment_provider_customer_error",
"payment_provider_customer_error": {
"lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"payment_provider": "stripe",
"provider_error": {
"message": "Invalid email address",
"error_code": "email_invalid"
}
}
}
AttributesDescription
lago_id     String     Not nullUnique identifer of the customer in Lago application
external_id     String     Not nullUnique identifer of the customer in your application
payment_provider     StringPayment provider used to process the payment
provider_error[message]     StringError message sent by the payment provider
provider_error[error_code]     StringError code sent by the payment provider
Checkout URL generated
Sent when a new customer is created through integration with GoCardless.

Includes the URL that should be used to set up the direct debit mandate.

{
"webhook_type": "customer.checkout_url_generated",
"object_type": "payment_provider_customer_checkout_url",
"payment_provider_customer_checkout_url": {
"lago_customer_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
"external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"payment_provider": "gocardless",
"checkout_url": "__CUSTOM_CHECKOUT_URL__"
}
}
AttributesDescription
lago_customer_id     String     Not nullUnique identifer of the customer in Lago
external_customer_id     String     Not nullUnique identifer of the customer in your application
payment_provider     String     Not nullDefault payment provider for this customer
checkout_url     String     Not nullURL that should be used to set up the direct debit mandate
Payment failure
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.

{
"webhook_type": "invoice.payment_failure",
"object_type": "payment_provider_invoice_payment_error",
"payment_provider_invoice_payment_error": {
"lago_invoice_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"lago_customer_id": "99a6094e-199b-4101-896a-54e927ce7bd7",
"external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"provider_customer_id": "cus_123456",
"payment_provider": "stripe",
"provider_error": {
"message": "Cannot charge a customer that has no active card",
"error_code": "missing"
}
}
}
AttributesDescription
lago_invoice_id     String     Not nullUnique identifer of the invoice in Lago application
lago_customer_id     String     Not nullUnique identifer of the customer in Lago application
external_customer_id     String     Not nullUnique identifer of the customer in your application
provider_customer_id     String     Not nullUnique identifer of the customer in payment provider application
payment_provider     StringPayment provider used to process the payment
provider_error[message]     StringError message sent by the payment provider
provider_error[error_code]     StringError code sent by the payment provider
Refund failure
This webhook is sent when there is an error related to a credit note refund of a payment previously created on a payment provider.
{
"webhook_type": "credit_note.refund_failure",
"object_type": "payment_provider_customer_error",
"credit_note_payment_provider_refund_error": {
"lago_credit_note_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"lago_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"provider_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
"payment_provider": "stripe",
"provider_error": {
"message": "error message",
"code": "error_code"
},
}
}
AttributesDescription
lago_credit_note_id     String     Not nullUnique identifer of the credit note in Lago application
lago_customer_id     String     Not nullUnique identifer of the customer in Lago application
external_customer_id     String     Not nullUnique identifer of the customer in your application
provider_customer_id     String     Not nullUnique identifer of the customer in payment provider
payment_provider     String     Not nullPayment provider used to process the payment
provider_error[message]     StringError message sent by the payment provider
provider_error[error_code]     StringError message sent by the payment provider
Event error
This webhook is sent when there is an error related to the creation of an event.
{
"webhook_type": "event.error",
"object_type": "event_error",
"event_error": {
"status": 422,
"error": "Unprocessable entity",
"message": "code does not exist",
"input_params": {
"transaction_id": "__transaction_id__",
"external_customer_id": "customer123",
"code": "code123"
}
}
}
AttributesDescription
status     String     Not nullHTTP status of the error. Possible statuses are 404 or 422
error     String     Not nullHTTP error code. Possible errors are Not found or Unprocessable entity
message     String     Not nullError code. See next list for the description of each error code.
input_params     JSON     Not nullJSON provided at event creation
CodeDescription
billable_metric_not_found     404No billable metric matches the given code
customer_not_found     404No customer matches the external id
subscription_not_found     404No subscription matches the given external subscription id
invalid_argument     422No subscription matches the given external subscription id
invalid_recurring_resource     422Provided recurring resource for persisted event is invalid
Subscription terminated
Sent when a subscription is terminated.
{
"webhook_type": "subscription.terminated",
"object_type": "subscription",
"subscription": {
"lago_id": "0fd99089-b15a-abcd-1234-a8292df18990",
"external_id": "custom_sub_id_1234",
"lago_customer_id": "27b9c2d9-abcd-1234-898f-hyt29a8e0eea",
"external_customer_id": "customer_1234",
"name": "",
"plan_code": "premium",
"status": "terminated",
"billing_time": "anniversary",
"subscription_at": "2023-01-11T10:51:29Z",
"started_at": "2023-01-11T10:51:29Z",
"terminated_at": "2023-01-24T14:53:02Z",
"canceled_at": null,
"created_at": "2023-01-11T10:51:34Z",
"previous_plan_code": null,
"next_plan_code": null,
"downgrade_plan_date": null,
"subscription_date": "2023-01-11"
}
}
AttributesDescription
subscription     JSON     Not nullableSubscription object