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

Entity	Identifier Field
Customer	customerId
Subscription	subscriptionId
Order	orderId
Product Offering	productOfferingId
Payment Link	paymentLinkId
Payment Session	paymentSessionId
Invoice	invoiceId
License	licenseId

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.