Messages
Here is the list of webhook messages sent by Lago.
Draft invoice created
{
"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
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
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
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
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
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
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 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
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
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
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
{
"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
{
"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
{
"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 |