# Create Subscription

Create a new subscription linking a billable entity to a rate.

Validation: The billable entity must be associated with ALL accounts referenced
in the allocation configuration. This is validated via Profile Service.

Billing Frequency:
- DAILY - Charges generated daily
- WEEKLY - Charges generated weekly (anchorDay = day of week 1-7)
- BIWEEKLY - Charges generated every two weeks
- MONTHLY - Charges generated monthly (anchorDay = day of month 1-31)

Endpoint: POST /subscriptions
Version: 1.0.0
Security: OAuth2

## Request fields (application/json):

  - `billableEntityId` (string, required)

  - `rateId` (string, required)

  - `allocationConfigId` (string, required)

  - `discountRateIds` (array)

  - `billingFrequency` (string, required)
    Billing frequency for subscriptions
    Enum: "DAILY", "WEEKLY", "BIWEEKLY", "MONTHLY"

  - `billingAnchorDay` (integer, required)

  - `billingTimezone` (string, required)

  - `startDate` (string, required)

  - `endDate` (string)

## Response 201 fields (application/json):

  - `id` (string, required)

  - `entityId` (string, required)

  - `billableEntityId` (string, required)
    Reference to BillableEntity in Profile Service

  - `rateId` (string, required)

  - `allocationConfigId` (string, required)

  - `discountRateIds` (array)
    Discount rates to apply

  - `billingFrequency` (string, required)
    Billing frequency for subscriptions
    Enum: "DAILY", "WEEKLY", "BIWEEKLY", "MONTHLY"

  - `billingAnchorDay` (integer, required)
    Day of week (1-7) for WEEKLY/BIWEEKLY, day of month (1-31) for MONTHLY

  - `billingTimezone` (string, required)
    IANA timezone for billing calculations
    Example: "America/New_York"

  - `startDate` (string, required)

  - `endDate` (string,null)

  - `status` (string, required)
    Status of subscription
    Enum: "ACTIVE", "PAUSED", "CANCELLED"

  - `version` (integer, required)
    Business version number for change tracking (subscription configuration history)

  - `optimisticLockVersion` (integer)
    Optimistic locking version (managed by Hibernate @Version). Prevents concurrent update conflicts.

  - `createdAt` (string, required)

  - `updatedAt` (string)

## Response 400 fields (application/json):

  - `result` (object, required)

  - `result.status` (string, required)
    Response status (always ERROR for error responses)
    Enum: "ERROR"

  - `error` (object, required)

  - `error.responseCode` (string, required)
    Response code (numeric or contains numbers, e.g., "404", "409", "500", "ERR001")
    Example: "404"

  - `error.responseMessage` (array, required)
    Array of error message strings for multiple error details
    Example: ["Charge not found","The requested charge ID does not exist in the system"]

## Response 401 fields (application/json):

  - `result` (object, required)

  - `result.status` (string, required)
    Response status (always ERROR for error responses)
    Enum: "ERROR"

  - `error` (object, required)

  - `error.responseCode` (string, required)
    Response code (numeric or contains numbers, e.g., "404", "409", "500", "ERR001")
    Example: "404"

  - `error.responseMessage` (array, required)
    Array of error message strings for multiple error details
    Example: ["Charge not found","The requested charge ID does not exist in the system"]