Context

Currently our swatch-contracts API responses include an internal `subscriptionId` field (used as part of the composite primary key) alongside `subscriptionNumber`. For external consumers, the `subscriptionNumber` is the meaningful identifier that corresponds to actual subscription numbers from upstream systems. We need to expose `subscriptionNumber` in API responses that currently return the internal `subscriptionId`, and remove `subscriptionId` from POJOs where it's not needed.

👉 Part of SWATCH-3767 data model consolidation epic - enables notifications epic dependency chain

*Current Implementation Analysis:*

• `SubscriptionEntity` has both fields: `subscriptionId` (line 66, part of composite PK) and `subscriptionNumber` (line 70)
• `SkuCapacitySubscription` schema already returns both `id` and `number` fields (openapi.yaml:1608-1613)
• V1/V2 subscription APIs in `/api/rhsm-subscriptions/v*/subscriptions/products/ {product_id}

  ` currently expose both

• The mapping appears to be: `id` field = `subscriptionId`, `number` field = `subscriptionNumber`

Out of Scope

• Changing database schema or primary key structure
• Modifying internal service-to-service communication that legitimately needs subscriptionId
• Altering the composite primary key implementation (subscriptionId + startDate)
• Changes to database queries or repository layer beyond POJO updates
• Updating other services' APIs (this is swatch-contracts specific)

Acceptance Criteria

Must Have

• Document current API response structure showing both id/number fields are already exposed
• Verify external-facing APIs consistently return subscriptionNumber as primary identifier
• Identify and remove subscriptionId from UsageEvent POJOs where mentioned in requirements
• Update API documentation to clarify field usage (id=internal, number=external identifier)
• Validate that existing API consumers can transition from id to number field

Should Have

• Add API examples showing recommended usage of number field over id field
• Document migration path for API consumers currently using id field
• Verify no breaking changes to existing API contracts

Could Have

• Add deprecation notices for id field usage where appropriate
• Include field usage documentation in OpenAPI descriptions

Won't Have

• Database schema changes or primary key modifications
• Changes to repository/entity layer beyond POJO cleanup
• Internal service communication modifications
• Migration of historical data

Technical Analysis Required

• Search for UsageEvent classes mentioned in requirements (not found in swatch-contracts)
• Verify all public API endpoints consistently expose both fields
• Document the current id/number field mapping in API responses
• Identify any POJOs that unnecessarily include subscriptionId

Done

• Documentation (PR) with:
  • Current API field mapping documented (id=subscriptionId, number=subscriptionNumber)
  • UsageEvent POJOs cleaned up to remove unnecessary subscriptionId references
  • API documentation updated to clarify field usage recommendations
  • Examples showing proper use of subscriptionNumber for external integrations
  • Migration guidance for API consumers transitioning from id to number field
  • Validation that no breaking changes introduced to existing API contracts
  • Demo showing API responses with clear field usage patterns