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": []
}
}
| Attributes | Description |
|---|---|
| invoice JSON Not nullable | Invoice 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"
}
]
}
}
| Attributes | Description |
|---|---|
| invoice JSON Not nullable | Invoice 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",
}
}
| Attributes | Description |
|---|---|
| invoice JSON Not nullable | Invoice 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
}
]
}
}
| Attributes | Description |
|---|---|
| invoice JSON Not nullable | Invoice 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
}
]
}
}
| Attributes | Description |
|---|---|
| invoice JSON Not nullable | Invoice 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
}
}
]
}
}
| Attributes | Description |
|---|---|
| credit_note JSON Not nullable | Credit 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
}
}
]
}
}
| Attributes | Description |
|---|---|
| credit_note JSON Not nullable | Credit 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"
}
}
}
| Attributes | Description |
|---|---|
| customer JSON Not nullable | Customer 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"
}
}
}
| Attributes | Description |
|---|---|
| lago_id String Not null | Unique identifer of the customer in Lago application |
| external_id String Not null | Unique identifer of the customer in your application |
| payment_provider String | Payment provider used to process the payment |
| provider_error[message] String | Error message sent by the payment provider |
| provider_error[error_code] String | Error 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__"
}
}
| Attributes | Description |
|---|---|
| lago_customer_id String Not null | Unique identifer of the customer in Lago |
| external_customer_id String Not null | Unique identifer of the customer in your application |
| payment_provider String Not null | Default payment provider for this customer |
| checkout_url String Not null | URL 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"
}
}
}
| Attributes | Description |
|---|---|
| lago_invoice_id String Not null | Unique identifer of the invoice in Lago application |
| lago_customer_id String Not null | Unique identifer of the customer in Lago application |
| external_customer_id String Not null | Unique identifer of the customer in your application |
| provider_customer_id String Not null | Unique identifer of the customer in payment provider application |
| payment_provider String | Payment provider used to process the payment |
| provider_error[message] String | Error message sent by the payment provider |
| provider_error[error_code] String | Error 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"
},
}
}
| Attributes | Description |
|---|---|
| lago_credit_note_id String Not null | Unique identifer of the credit note in Lago application |
| lago_customer_id String Not null | Unique identifer of the customer in Lago application |
| external_customer_id String Not null | Unique identifer of the customer in your application |
| provider_customer_id String Not null | Unique identifer of the customer in payment provider |
| payment_provider String Not null | Payment provider used to process the payment |
| provider_error[message] String | Error message sent by the payment provider |
| provider_error[error_code] String | Error 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"
}
}
}
| Attributes | Description |
|---|---|
| status String Not null | HTTP status of the error. Possible statuses are 404 or 422 |
| error String Not null | HTTP error code. Possible errors are Not found or Unprocessable entity |
| message String Not null | Error code. See next list for the description of each error code. |
| input_params JSON Not null | JSON provided at event creation |
| Code | Description |
|---|---|
| billable_metric_not_found 404 | No billable metric matches the given code |
| customer_not_found 404 | No customer matches the external id |
| subscription_not_found 404 | No subscription matches the given external subscription id |
| invalid_argument 422 | No subscription matches the given external subscription id |
| invalid_recurring_resource 422 | Provided 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"
}
}
| Attributes | Description |
|---|---|
| subscription JSON Not nullable | Subscription object |