Messages

Here is the complete list of webhook messages sent by Lago.

Event ingestion

Events errors

Sent by the health check process when some events received in the previous hour do not match the validation rules.

  {
    "webhook_type": "events.errors",
    "object_type": "events_errors",
    "events_errors": {
      "invalid_code": ["__transaction_id__"],
      "missing_aggregation_property": ["__transaction_id__"],
      "missing_group_key": ["__transaction_id__"]
    }
  }

Arguments

invalid_code · array · required

List of events transaction_id for which the code attribute does not match an existing billable metric.

missing_aggregation_property · array · required

List of events transaction_id for which the aggregation property defined in the billable metric field_name attribute is missing or invalid.

missing_group_key · array · required

List of events transaction_id for which the groups properties defined at the billable metric level are missing or invalid.

Event error [deprecated]

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.

  {
    "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"
      }
    }
  }

Arguments

status · string · required

HTTP status of the error. Possible statuses are 404 or 422.

error · string · required

HTTP error code. Possible errors are Not found or Unprocessable entity.

message · string · required

Error code. See next list for the description of each error code.

input_params · string · required

JSON provided at event creation.

Errors

Error	Code	Description
404	billable_metric_not_found	No billable metric matches the given code
404	customer_not_found	No customer matches the external id
404	subscription_not_found	No subscription matches the given external subscription id
422	invalid_argument	No subscription matches the given external subscription id
422	invalid_recurring_resource	Provided recurring resource for persisted event is invalid

Invoices

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,
          "lago_true_up_fee_id": null,
          "lago_true_up_parent_fee_id": null,
          "item": {
            "type": "subscription",
            "code": "corporate",
            "name": "Corporate"
          },
          "amount_cents": 5500,
          "amount_currency": "USD",
          "vat_amount_cents": 0,
          "vat_amount_currency": "USD",
          "total_amount_cents": 5500,
          "total_amount_currency": "EUR",
          "units": "1.0",
          "events_count": null
        }
      ],
      "credits": []
    }
  }

Arguments

invoice · JSON · required

Returning an invoice object.

Finalized invoice created

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.

{
  "webhook_type": "invoice.created",
  "object_type": "invoice",
  "invoice": {
    "lago_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "sequential_id": 2,
    "number": "LAG-1234-001-002",
    "issuing_date": "2022-04-29",
    "invoice_type": "subscription",
    "status": "finalized",
    "payment_status": "succeeded",
    "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": "[e-mail]",
      "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",
        "lago_group_id": null,
        "lago_true_up_fee_id": null,
        "lago_true_up_parent_fee_id": null,
        "item": {
          "type": "subscription",
          "code": "plan_code",
          "name": "Plan"
        },
        "amount_cents": 100,
        "amount_currency": "EUR",
        "vat_amount_cents": 20,
        "vat_amount_currency": "EUR",
        "total_amount_cents": 120,
        "total_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"
      }
    ]
  }
}

Arguments

invoice · JSON · required

Returning an invoice object.

One-off invoice created

Sent when a one-off invoice is created. Only add-ons can be applied to one-off invoices.

  {
    "webhook_type": "invoice.one_off_created",
    "object_type": "invoice",
    "invoice": {
      "lago_id": "b7b6a31f-b81b-4ae5-a9c8-05c407e47416",
      "sequential_id": 4,
      "number": "ONE-0499-001-004",
      "issuing_date": "2023-05-05",
      "invoice_type": "one_off",
      "status": "finalized",
      "payment_status": "pending",
      "currency": "USD",
      "fees_amount_cents": 25000,
      "vat_amount_cents": 2500,
      "coupons_amount_cents": 0,
      "credit_notes_amount_cents": 0,
      "sub_total_vat_excluded_amount_cents": 25000,
      "sub_total_vat_included_amount_cents": 27500,
      "total_amount_cents": 27500,
      "prepaid_credit_amount_cents": 0,
      "file_url": null,
      "version_number": 3,
      "legacy": false,
      "amount_currency": "USD",
      "vat_amount_currency": "USD",
      "credit_amount_currency": "USD",
      "total_amount_currency": "USD",
      "amount_cents": 25000,
      "credit_amount_cents": 0,
      "customer": {
        "lago_id": "37cee916-5751-4665-9774-aa05bb1a2ffd",
        "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
        "name": "Gavin Belson",
        "sequential_id": 1,
        "slug": "TWI-2B86-001",
        "created_at": "2022-06-01T09:01:12Z",
        "country": "US",
        "address_line1": "5230 Penfield Ave",
        "address_line2": null,
        "state": "CA",
        "zipcode": "91364",
        "email": "[e-mail]",
        "city": "Woodland Hills",
        "url": "http://hooli.com",
        "phone": "1-171-883-3711 x245",
        "logo_url": "http://hooli.com/logo.png",
        "legal_name": "Coleman-Blair",
        "legal_number": "49-008-2965",
        "currency": "USD",
        "timezone": null,
        "applicable_timezone": "UTC",
        "billing_configuration": {
          "invoice_grace_period": null,
          "payment_provider": null,
          "vat_rate": 0,
          "document_locale": null
        }
      },
      "fees": [
        {
          "lago_id": "5fe06606-25c8-4aa8-bce8-a19a12383d51",
          "lago_group_id": null,
          "lago_invoice_id": "b7b6a31f-b81b-4ae5-a9c8-05c407e47416",
          "lago_true_up_fee_id": null,
          "lago_true_up_parent_fee_id": null,
          "item": {
            "type": "add_on",
            "code": "setup_fee",
            "name": "Setup Fee",
            "lago_item_id": "b3f1967d-bf84-44a7-b3e9-207024a6aaa5",
            "item_type": "AddOn"
          },
          "amount_cents": 5000,
          "amount_currency": "USD",
          "vat_amount_cents": 500,
          "vat_amount_currency": "USD",
          "total_amount_cents": 5500,
          "total_amount_currency": "USD",
          "units": "5.0",
          "description": "",
          "unit_amount_cents": 1000,
          "events_count": null,
          "payment_status": "pending",
          "created_at": "2023-05-05T15:05:27Z",
          "succeeded_at": null,
          "failed_at": null,
          "refunded_at": null
        },
        {
          "lago_id": "a74705a1-05f2-41cb-b315-ab0c858c215d",
          "lago_group_id": null,
          "lago_invoice_id": "b7b6a31f-b81b-4ae5-a9c8-05c407e47416",
          "lago_true_up_fee_id": null,
          "lago_true_up_parent_fee_id": null,
          "item": {
            "type": "add_on",
            "code": "customer_success_fee",
            "name": "Customer Success",
            "lago_item_id": "66b75fbf-3410-4251-9105-b4b3d5922a1d",
            "item_type": "AddOn"
          },
          "amount_cents": 20000,
          "amount_currency": "USD",
          "vat_amount_cents": 2000,
          "vat_amount_currency": "USD",
          "total_amount_cents": 22000,
          "total_amount_currency": "USD",
          "units": "1.0",
          "description": "My new description",
          "unit_amount_cents": 20000,
          "events_count": null,
          "payment_status": "pending",
          "created_at": "2023-05-05T15:05:27Z",
          "succeeded_at": null,
          "failed_at": null,
          "refunded_at": null
        }
      ]
    }
  }

Arguments

invoice · JSON · required

Returning an 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": "0e77ace9-68ba-0000-aaaa-999888c43f75",
      "sequential_id": 14,
      "number": "SEL-AZ22-034-014",
      "issuing_date": "2023-04-24",
      "invoice_type": "credit",
      "status": "finalized",
      "payment_status": "pending",
      "currency": "USD",
      "fees_amount_cents": 100,
      "amount_cents": 100,
      "vat_amount_cents": 0,
      "coupons_amount_cents": 0,
      "credit_notes_amount_cents": 0,
      "credit_amount_cents": 0,
      "total_amount_cents": 100,
      "prepaid_credit_amount_cents": 0,
      "file_url": null,
      "version_number": 2,
      "legacy": false,
      "amount_currency": "USD",
      "vat_amount_currency": "USD",
      "credit_amount_currency": "USD",
      "total_amount_currency": "USD",
      "customer": {
        "lago_id": "0e77ace9-68ba-1111-bbbb-999888c43f75",
        "external_id": "customer_1234",
        "name": "James White",
        "sequential_id": 34,
        "slug": "SEL-AZ22-034",
        "created_at": "2023-04-19T21:49:37Z",
        "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": "UTC",
        "billing_configuration": {
          "invoice_grace_period": null,
          "payment_provider": null,
          "vat_rate": null,
          "document_locale": null
        }
      },
      "fees": [
        {
          "lago_id": "0e77ace9-68ba-3333-hhhh-999888c43f75",
          "lago_group_id": null,
          "lago_invoice_id": "0e77ace9-68ba-4444-pppp-999888c43f75",
          "lago_true_up_fee_id": null,
          "lago_true_up_parent_fee_id": null,
          "item": {
            "type": "credit",
            "code": "credit",
            "name": "credit",
            "lago_item_id": "0e77ace9-68ba-9999-rrrr-999888c43f75",
            "item_type": "WalletTransaction"
          },
          "amount_cents": 100,
          "amount_currency": "USD",
          "vat_amount_cents": 0,
          "vat_amount_currency": "USD",
          "total_amount_cents": 100,
          "total_amount_currency": "USD",
          "units": "1.0",
          "events_count": null,
          "external_subscription_id": null,
          "payment_status": "pending",
          "created_at": "2023-04-24T08:47:43Z",
          "succeeded_at": null,
          "failed_at": null,
          "refunded_at": null
        }
      ]
    }
  }

Arguments

invoice · JSON · required

Returning an 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",
  }
}

Arguments

invoice · JSON · required

Returning an invoice object.

Payment status updated

Sent when the payment status of an invoice is updated based on information provided by the payment provider.

{
  "webhook_type": "invoice.payment_status_updated",
  "object_type": "invoice",
  "invoice": {
    "lago_id": "68133479-abcd-1234-5678-jklm437da000",
    "sequential_id": 1,
    "number": "SEL-AZ22-040-XXX",
    "issuing_date": "2023-04-24",
    "invoice_type": "subscription",
    "status": "finalized",
    "payment_status": "succeeded",
    "currency": "USD",
    "fees_amount_cents": 70,
    "amount_cents": 70,
    "vat_amount_cents": 11,
    "coupons_amount_cents": 0,
    "credit_notes_amount_cents": 0,
    "credit_amount_cents": 0,
    "total_amount_cents": 81,
    "prepaid_credit_amount_cents": 0,
    "file_url": null,
    "version_number": 2,
    "legacy": false,
    "amount_currency": "USD",
    "vat_amount_currency": "USD",
    "credit_amount_currency": "USD",
    "total_amount_currency": "USD",
    "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": "[e-mail]",
      "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"
    }
  }
}

Arguments

invoice · JSON · required

Returning an invoice object.

Subscriptions and fees

Fee created

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 that need to create a statement of transactions without invoicing.

  {
  "webhook_type": "fee.created",
  "object_type": "fee",
  "fee": {
    "lago_id": "6be23c42-47d2-45a3-9770-5b3572f225c3",
    "lago_group_id": "5b4881e3-b451-472e-9e03-d99379550743",
    "lago_true_up_fee_id": null,
    "lago_true_up_parent_fee_id": null,
    "item": {
      "type": "charge",
      "code": "fx_transfer",
      "name": "FX Transfer"
    },
    "amount_cents": 100,
    "amount_currency": "EUR",
    "vat_amount_cents": 20,
    "vat_amount_currency": "EUR",
    "total_amount_cents": 120,
    "total_amount_currency": "EUR",
    "units": "0.32",
    "events_count": 23
  }
}

Arguments

fee · JSON · required

Returning a fee object.

Subscription started

Sent when a subscription starts.

{
  "webhook_type": "subscription.started",
  "object_type": "subscription",
  "subscription": {
    "lago_id": "c87f2b9d-c5ce-4e3b-ba3c-b21c9ce41e21",
    "external_id": "efb9a89e-e63d-4c55-8509-2dbc94fc61ce",
    "lago_customer_id": "fbed2045-018c-4e5f-aa04-a44026fe0a63",
    "external_customer_id": "advance_2",
    "name": "",
    "plan_code": "plan_advance_100",
    "status": "active",
    "billing_time": "anniversary",
    "subscription_at": "2023-08-23T15:11:52Z",
    "ending_at": "2024-08-23T15:11:57Z",
    "started_at": "2023-08-23T15:11:52Z",
    "terminated_at": null,
    "canceled_at": null,
    "created_at": "2023-08-23T15:11:57Z",
    "previous_plan_code": null,
    "next_plan_code": null,
    "downgrade_plan_date": null,
    "subscription_date": "2023-08-23",
    "trial_ended_at": "2023-08-23T15:10:28Z",
    "customer": {
      "lago_id": "fbed2045-018c-4e5f-aa04-a44026fe0a63",
      "external_id": "advance_2",
      "name": "advance_2",
      "sequential_id": 2,
      "slug": "SUB-EB14-002",
      "created_at": "2023-08-23T15:10:28Z",
      "updated_at": "2023-08-23T15:10:36Z",
      "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",
      "tax_identification_number": null,
      "timezone": null,
      "applicable_timezone": "UTC",
      "net_payment_term": null,
      "external_salesforce_id": null,
      "billing_configuration": {
        "invoice_grace_period": null,
        "payment_provider": null,
        "vat_rate": null,
        "document_locale": null
      },
      "metadata": []
    },
    "plan": {
      "lago_id": "ca6765b6-aa7f-4fef-8b81-1fe731af0dfe",
      "name": "plan_advance_100",
      "created_at": "2023-08-23T14:43:11Z",
      "code": "plan_advance_100",
      "interval": "monthly",
      "description": "",
      "amount_cents": 10000,
      "amount_currency": "USD",
      "trial_period": 0,
      "pay_in_advance": true,
      "bill_charges_monthly": null,
      "active_subscriptions_count": 3,
      "draft_invoices_count": 0
    }
  }
}

Arguments

subscription · JSON · required

Returning a subscription object.

Subscription termination alert

Alert for imminent termination of subscriptions with set end dates, sent 45 days and 15 days prior (at fixed intervals).

{
  "webhook_type": "subscription.termination_alert",
  "object_type": "subscription",
  "subscription": {
    "lago_id": "c87f2b9d-c5ce-4e3b-ba3c-b21c9ce41e21",
    "external_id": "efb9a89e-e63d-4c55-8509-2dbc94fc61ce",
    "lago_customer_id": "fbed2045-018c-4e5f-aa04-a44026fe0a63",
    "external_customer_id": "advance_2",
    "name": "",
    "plan_code": "plan_advance_100",
    "status": "active",
    "billing_time": "anniversary",
    "subscription_at": "2023-08-23T15:11:52Z",
    "started_at": "2023-08-23T15:11:52Z",
    "terminated_at": null,
    "canceled_at": null,
    "created_at": "2023-08-23T15:11:57Z",
    "ending_at": "2024-08-23T15:11:57Z",
    "previous_plan_code": null,
    "next_plan_code": null,
    "downgrade_plan_date": null,
    "subscription_date": "2023-08-23",
    "trial_ended_at": "2023-08-23T15:10:28Z",
    "customer": {
      "lago_id": "fbed2045-018c-4e5f-aa04-a44026fe0a63",
      "external_id": "advance_2",
      "name": "advance_2",
      "sequential_id": 2,
      "slug": "SUB-EB14-002",
      "created_at": "2023-08-23T15:10:28Z",
      "updated_at": "2023-08-23T15:10:36Z",
      "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",
      "tax_identification_number": null,
      "timezone": null,
      "applicable_timezone": "UTC",
      "net_payment_term": null,
      "external_salesforce_id": null,
      "billing_configuration": {
        "invoice_grace_period": null,
        "payment_provider": null,
        "vat_rate": null,
        "document_locale": null
      },
      "metadata": []
    },
    "plan": {
      "lago_id": "ca6765b6-aa7f-4fef-8b81-1fe731af0dfe",
      "name": "plan_advance_100",
      "created_at": "2023-08-23T14:43:11Z",
      "code": "plan_advance_100",
      "interval": "monthly",
      "description": "",
      "amount_cents": 10000,
      "amount_currency": "USD",
      "trial_period": 0,
      "pay_in_advance": true,
      "bill_charges_monthly": null,
      "active_subscriptions_count": 3,
      "draft_invoices_count": 0
    }
  }
}

Arguments

subscription · JSON · required

Returning a subscription object.

Subscription terminated

Sent when a subscription is terminated.

{
  "webhook_type": "subscription.terminated",
  "object_type": "subscription",
  "subscription": {
    "lago_id": "084b0581-0052-469d-809f-846d1944861b",
    "external_id": "b0f9804a-5a84-41fb-9a1b-c5e35db4ecec",
    "lago_customer_id": "fbed2045-018c-4e5f-aa04-a44026fe0a63",
    "external_customer_id": "advance_2",
    "name": "",
    "plan_code": "plan_advance_100",
    "status": "terminated",
    "billing_time": "anniversary",
    "subscription_at": "2023-08-23T15:10:28Z",
    "ending_at": "2024-08-23T15:11:57Z",
    "started_at": "2023-08-23T15:10:28Z",
    "terminated_at": "2023-08-23T15:12:23Z",
    "canceled_at": null,
    "created_at": "2023-08-23T15:10:36Z",
    "previous_plan_code": null,
    "next_plan_code": null,
    "downgrade_plan_date": null,
    "subscription_date": "2023-08-23",
    "trial_ended_at": "2023-08-23T15:10:28Z",
    "customer": {
      "lago_id": "fbed2045-018c-4e5f-aa04-a44026fe0a63",
      "external_id": "advance_2",
      "name": "advance_2",
      "sequential_id": 2,
      "slug": "SUB-EB14-002",
      "created_at": "2023-08-23T15:10:28Z",
      "updated_at": "2023-08-23T15:10:36Z",
      "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",
      "tax_identification_number": null,
      "timezone": null,
      "applicable_timezone": "UTC",
      "net_payment_term": null,
      "external_salesforce_id": null,
      "billing_configuration": {
        "invoice_grace_period": null,
        "payment_provider": null,
        "vat_rate": null,
        "document_locale": null
      },
      "metadata": []
    },
    "plan": {
      "lago_id": "ca6765b6-aa7f-4fef-8b81-1fe731af0dfe",
      "name": "plan_advance_100",
      "created_at": "2023-08-23T14:43:11Z",
      "code": "plan_advance_100",
      "interval": "monthly",
      "description": "",
      "amount_cents": 10000,
      "amount_currency": "USD",
      "trial_period": 0,
      "pay_in_advance": true,
      "bill_charges_monthly": null,
      "active_subscriptions_count": 3,
      "draft_invoices_count": 0
    }
  }
}

Arguments

subscription · JSON · required

Returning a subscription object.

Subscription upgraded/downgraded

When a subscription undergoes an upgrade or downgrade, you will be notified via two webhook messages as follows:

1. subscription.terminated for the initial plan, which includes the property next_plan_code populated with the code of the new plan.
2. subscription.started for the new plan, which includes the property previous_plan_code populated with the code of the initial plan.

Subscription trial ended

Sent when the free trial is ended for a subscription.

{
  "webhook_type": "subscription.trial_ended",
  "object_type": "subscription",
  "subscription": {
    "lago_id": "084b0581-0052-469d-809f-846d1944861b",
    "external_id": "b0f9804a-5a84-41fb-9a1b-c5e35db4ecec",
    "lago_customer_id": "fbed2045-018c-4e5f-aa04-a44026fe0a63",
    "external_customer_id": "advance_2",
    "name": "",
    "plan_code": "plan_advance_100",
    "status": "terminated",
    "billing_time": "anniversary",
    "subscription_at": "2023-08-23T15:10:28Z",
    "ending_at": "2024-08-23T15:11:57Z",
    "started_at": "2023-08-23T15:10:28Z",
    "terminated_at": "2023-08-23T15:12:23Z",
    "canceled_at": null,
    "created_at": "2023-08-23T15:10:36Z",
    "previous_plan_code": null,
    "next_plan_code": null,
    "downgrade_plan_date": null,
    "subscription_date": "2023-08-23",
    "trial_ended_at": "2023-08-23T15:10:28Z",
    "customer": {
      "lago_id": "fbed2045-018c-4e5f-aa04-a44026fe0a63",
      "external_id": "advance_2",
      "name": "advance_2",
      "sequential_id": 2,
      "slug": "SUB-EB14-002",
      "created_at": "2023-08-23T15:10:28Z",
      "updated_at": "2023-08-23T15:10:36Z",
      "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",
      "tax_identification_number": null,
      "timezone": null,
      "applicable_timezone": "UTC",
      "net_payment_term": null,
      "external_salesforce_id": null,
      "billing_configuration": {
        "invoice_grace_period": null,
        "payment_provider": null,
        "vat_rate": null,
        "document_locale": null
      },
      "metadata": []
    },
    "plan": {
      "lago_id": "ca6765b6-aa7f-4fef-8b81-1fe731af0dfe",
      "name": "plan_advance_100",
      "created_at": "2023-08-23T14:43:11Z",
      "code": "plan_advance_100",
      "interval": "monthly",
      "description": "",
      "amount_cents": 10000,
      "amount_currency": "USD",
      "trial_period": 0,
      "pay_in_advance": true,
      "bill_charges_monthly": null,
      "active_subscriptions_count": 3,
      "draft_invoices_count": 0
    }
  }
}

Arguments

subscription · JSON · required

Returning a subscription object.

Wallets

Wallet transaction created

Sent when a wallet transaction is created.

{
  "webhook_type": "wallet_transaction.created",
  "object_type": "wallet_transaction",
  "wallet_transaction": {
    "lago_id": "773e24d0-28f3-4af5-b5c4-207557b0beeb",
    "lago_wallet_id": "103f64c4-933b-467f-8786-dd3c0f6fab97",
    "status": "pending",
    "transaction_status": "purchased",
    "transaction_type": "inbound",
    "amount": "100.0",
    "credit_amount": "100.0",
    "settled_at": null,
    "created_at": "2024-04-23T11:31:43Z"
  }
}

Arguments

wallet_transaction · JSON · required

Returning a wallet transaction object.

Wallet transaction updated

Sent when a wallet transaction is updated. For example, when wallet transaction is marked as settled.

{
  "webhook_type": "wallet_transaction.updated",
  "object_type": "wallet_transaction",
  "wallet_transaction": {
    "lago_id": "773e24d0-28f3-4af5-b5c4-207557b0beeb",
    "lago_wallet_id": "103f64c4-933b-467f-8786-dd3c0f6fab97",
    "status": "settled",
    "transaction_status": "purchased",
    "transaction_type": "inbound",
    "amount": "100.0",
    "credit_amount": "100.0",
    "settled_at": "2024-04-23T11:31:43Z",
    "created_at": "2024-04-23T11:31:43Z"
  }
}

Arguments

wallet_transaction · JSON · required

Returning a wallet transaction object.

Wallet - Depleted ongoing balance

Sent when the ongoing balance is negative or equal to 0.

{
  "webhook_type": "wallet.depleted_ongoing_balance",
  "object_type": "wallet",
  "wallet": {
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "external_customer_id": "hooli_1234",
    "status": "active",
    "currency": "USD",
    "name": "Prepaid",
    "rate_amount": "1.0",
    "credits_balance": "8.0",
    "balance_cents": 800,
    "consumed_credits": "0.0",
    "created_at": "2022-04-29T08:59:51Z",
    "expiration_at": "2023-11-07T05:31:56Z",
    "last_balance_sync_at": "2022-04-29T08:59:51Z",
    "last_consumed_credit_at": "2022-04-29T08:59:51Z",
    "terminated_at": "2022-09-14T16:35:31Z",
    "recurring_transaction_rules": [],
    "ongoing_balance_cents": 0,
    "ongoing_usage_balance_cents": 800,
    "credits_ongoing_balance": "0.0",
    "credits_ongoing_usage_balance": "8.0"
  }
}

Arguments

wallet · JSON · required

Returning a wallet object.

External payment providers

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": "[e-mail]",
      "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"
      }
    }
  }

Arguments

customer · JSON · required

Returning a customer object.

Checkout URL generated

Sent when a checkout link is issued for a customer.

  {
    "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__"
    }
  }

Arguments

lago_customer_id · String · required

Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer’s record within the Lago system.

external_customer_id · String · required

The customer external unique identifier (provided by your own application).

payment_provider · String · required

The default payment provider attached to this customer.

checkout_url · String · required

URL that should be utilized to set up the payment method within the payment provider’s system.

Payment provider error

This webhook is sent when there is an error related to the creation of a customer in the payment provider’s system.

  {
    "webhook_type": "customer.payment_provider_error",
    "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"
      }
    }
  }

Arguments

lago_id · String · required

Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer’s record within the Lago system.

external_id · String · required

The customer external unique identifier (provided by your own application).

payment_provider · String · required

The default payment provider attached to this customer.

provider_error[message] · String · required

The error message sent by the payment provider.

provider_error[error_code] · String · required

The error code sent by the payment provider.

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"
      }
    }
  }

Arguments

lago_invoice_id · String · required

Unique identifer of the invoice in Lago application.

lago_customer_id · String · required

Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer’s record within the Lago system.

external_customer_id · String · required

The customer external unique identifier (provided by your own application).

provider_customer_id · String · required

Unique identifer of the customer in payment provider application.

payment_provider · String · required

The default payment provider attached to this customer.

provider_error[message] · String · required

The error message sent by the payment provider.

provider_error[error_code] · String · required

The error code sent by the payment provider.

Payment dispute lost

This notification is sent whenever a dispute or a chargeback is lost within your payment provider.

  {
"webhook_type": "invoice.payment_dispute_lost",
"object_type": "payment_dispute_lost",
"payment_dispute_lost": {
"invoice": {
  "lago_id": "95afbc14-70d4-41a0-855c-df348bd5c878",
  "sequential_id": 1,
  "number": "TWLO-202404-093",
  "issuing_date": "2024-04-15",
  "payment_due_date": "2024-04-15",
  "net_payment_term": 0,
  "invoice_type": "subscription",
  "status": "finalized",
  "payment_status": "pending",
  "payment_dispute_lost_at": "2024-04-16T12:48:01.176Z",
  "currency": "USD",
  "fees_amount_cents": 163000,
  "taxes_amount_cents": 32500,
  "coupons_amount_cents": 500,
  "credit_notes_amount_cents": 0,
  "sub_total_excluding_taxes_amount_cents": 162500,
  "sub_total_including_taxes_amount_cents": 195000,
  "total_amount_cents": 194900,
  "prepaid_credit_amount_cents": 100,
  "file_url": "https://main-api.staging.getlago.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaEpJaWt3TmpFMk56a3lNQzFtTWpOakxUUmxZMk10WWpVM1pDMDFZbUl3TjJJd09UVmpaamtHT2daRlZBPT0iLCJleHAiOm51bGwsInB1ciI6ImJsb2JfaWQifX0=--e9e5fce3554afcbcf2b2f531fdee9365cf44e732/TWLO-202404-093.pdf",
  "version_number": 4,
  "legacy": false,
  "amount_currency": "USD",
  "vat_amount_currency": "USD",
  "credit_amount_currency": "USD",
  "total_amount_currency": "USD",
  "amount_cents": 163000,
  "credit_amount_cents": 500,
  "vat_amount_cents": 32500,
  "sub_total_vat_excluded_amount_cents": 162500,
  "sub_total_vat_included_amount_cents": 195000,
  "customer": {
    "lago_id": "16ce2b87-0a1c-4474-a483-9c584059bbac",
    "external_id": "hooli_1234",
    "name": "Hooli 1234",
    "sequential_id": 111,
    "slug": "TWLO-111",
    "created_at": "2024-04-15T21:48:28Z",
    "updated_at": "2024-04-15T21:52:02Z",
    "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",
    "tax_identification_number": null,
    "timezone": null,
    "applicable_timezone": "UTC",
    "net_payment_term": null,
    "external_salesforce_id": "",
    "billing_configuration": {
      "invoice_grace_period": null,
      "payment_provider": null,
      "payment_provider_code": null,
      "vat_rate": null,
      "document_locale": null
    },
    "metadata": []
  }
}
}
}

Credit notes and refunds

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",
          "total_amount_cents": 120,
          "total_amount_currency": "EUR",
          "units": 12.6,
          "events_count": 10
        }
      }
    ]
  }
}

Arguments

credit_note · JSON · required

Returning a 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",
          "total_amount_cents": 120,
          "total_amount_currency": "EUR",
          "units": 12.6,
          "events_count": 10
        }
      }
    ]
  }
}

Arguments

credit_note · JSON · required

Returning a credit note object.

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"
      },
    }
  }

Arguments

lago_credit_note_id · String · required

Unique identifer of the credit note in Lago application.

lago_customer_id · String · required

Unique identifer of the customer in Lago application.

external_customer_id · String · required

Unique identifer of the customer in your application.

provider_customer_id · String · required

Unique identifer of the customer in payment provider’s system.

payment_provider · String · required

The payment provider used to process the payment.

provider_error[message] · String · required

The error message sent by the payment provider.

provider_error[error_code] · String · required

The error message sent by the payment provider.