String migration of resource identifiers

In Factorial, we keep growing to solve the problems of more and more customers. As the volume of customers and requests grows, our databases and backend processes are running into hardware and capacity limits.

One way of keep growing is horizontal scaling: instead of bigger databases or servers, you can distribute your customers into separate clusters with their own database and backend processes. This is the transformation we are working on right now. And it impacts how you manage identifiers: new databases will have an offset where they start to avoid clashes. If the original database starts all the identifiers at 1, the second cluster starts at 18446744073709550, the third one at 36893488147419100 and so on...

This new architecture will impact the public API. Starting with API version.2026-07-01, all resource identifiers (id fields and related reference fields) will be returned as strings instead of integers in both request parameters and response payloads. This also applies to webhook payloads, in order to accommodate these new huge values.

❗️

IDs are no longer guaranteed to fit within standard integer ranges. If your integration parses, stores, or compares IDs as numeric values, you may experience silent IDs corruption: big IDs will be changed with small values or the code will error. To avoid these issues, treat all IDs as opaque strings, just like UUIDs — do not cast them to integers or perform arithmetic operations on them.

Please update your code to handle string-typed IDs before migrating to this version.

See the table below for the full list of affected fields per resource.