Skip to main content

​
Conventions

The SeamlessOS API follows consistent design principles that make it predictable and easy to integrate with. Understanding these conventions helps you work more efficiently with the API.

​
Identifier naming

Specific identifier names - we use descriptive identifier field names like subscriptionId, customerId, and productOfferingId instead of generic id fields. This clearly indicates the entity type and eliminates ambiguity. Consistency across objects - the same identifier field name is used everywhere that entity appears, making it easy to join and filter on the same properties across different endpoints and responses.

​
Common identifier patterns

EntityIdentifier Field
CustomercustomerId
SubscriptionsubscriptionId
OrderorderId
Product OfferingproductOfferingId
Payment LinkpaymentLinkId
Payment SessionpaymentSessionId
InvoiceinvoiceId
LicenselicenseId

​
Backwards compatibility

All changes are backwards compatible - you can safely upgrade your integration without breaking existing functionality:
  • New fields: Added without affecting existing fields
  • New endpoints: Introduced alongside existing ones
  • New enum values: Added without removing existing values
  • Optional parameters: New optional fields don’t change required parameters
This means you can:
  • Update to newer API versions without code changes
  • Take advantage of new features when convenient
  • Maintain stable integrations with confidence
The result is an API that feels predictable and intuitive, reducing integration time and preventing common mistakes.
⌘I