[BUG]: Unexpected usage event timestamp behavior/documentation

[AnthonyEnr1quez]

Describe the bug
The request body for usage events defines a timestamp field that should be Unix Timestamp (ref). This field accepts an integer or a string.

We were erroneously sending a string value in the timestamp field with RFC3339 format (2024-12-10T17:36:46Z).

Somehow this was being parsed to the unix timestamp of 2024 and was being processed with the time of 1970-01-01T00:33:44Z.

This was causing fees to not be created, as we were unaware were processing with an incorrect timestamp and the behavior between the usage event timestamp and customer subscription start dates.

To Reproduce
Steps to reproduce the behavior:

1. Send usage event with RFC3339 formatted timestamp

curl --location 'https://api.getlago.com/api/v1/events' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer XXXXXXXXXXXXXXX' \
--data '{
      "event": {
          "transaction_id": "bfc89158-f994-4fde-b0e1-6ea7e25458f7",
          "external_subscription_id": "aee2c948-ce99-4a1b-af5b-42e25c860021",
          "code": "fee-created-test",
          "timestamp": "2024-12-10T17:36:46Z",
          "properties": {
            "volume": "100"
          }
      }
  }'

Example Response
Response Code: 200

{
    "event": {
        "lago_id": "f3f34932-ae0d-4d21-b0ff-0a1112004899",
        "transaction_id": "60f6005d-8e5a-4db9-9629-81b080b2f0cc",
        "lago_customer_id": null,
        "code": "fee-created-test",
        "timestamp": "1970-01-01T00:33:44.000Z",
        "precise_total_amount_cents": null,
        "properties": {
            "volume": "100"
        },
        "lago_subscription_id": null,
        "external_subscription_id": "aee2c948-ce99-4a1b-af5b-42e25c860021",
        "created_at": "2024-12-13T17:55:35Z"
    }
}

Expected behavior
A 400 or 422 response stating that the request/timestamp is invalid.

Screenshots

Additional context
This issue is happening on both the single and batch usage event endpoints.

There is conflicting documentation around the usage event timestamp field. Some places say its required, while others say it is not.

• https://getlago.com/docs/guide/events/ingesting-usage#send-usage-measurements-to-lago
• https://getlago.com/docs/guide/events/ingesting-usage#4-the-event-timestamp
• https://getlago.com/docs/api-reference/events/usage#response-event-timestamp

Version

• Lago: v1.15.0
• Lago Cloud

[annvelents]

Hello @AnthonyEnr1quez!
Thank you for pointing it out and sorry for the experienced inconveniences, this part might seem really confusing.

For the timestamp - because we accept both, string and integer, when we parse the received value, the way ruby works, when it parses a string into float (because we might receive floats to identify milliseconds), it goes through the string until the first not numeric value. That's why "2024-12-10..." becomes 2024, which is exactly "1970-01-01T00:33:44.000Z" - 2024 seconds after 'beginning of time' for the UNIX systems, so it is still kinda expected behaviour, but you're right, we can add a validation on the format of the received string.

For the inconsistency of the documentation - it is not required, I'll update it

[annvelents]

Hello @AnthonyEnr1quez!
Thank you once again for highlighting this issue. We've added a validation of the received timestamp, it will be included in the next release.
The documentation is updated as well, thanks! ;)

[AnthonyEnr1quez]

#2978
9410735