SubscriptionPeriod (v1.0.0)
Represents a single billing cycle or interval within a subscription's lifetime.
Overview
The SubscriptionPeriod entity tracks the state and details of a specific billing cycle within a Subscription. It links the subscription to the relevant invoice and payment for that interval and records the exact dates and amount billed.
Entity Properties
| Name | Type | Required | Description |
|---|---|---|---|
subscriptionPeriodId | UUID | Required | Unique identifier for this specific subscription period. |
subscriptionId | UUID | Required | Identifier of the parent Subscription this period belongs to. |
planId | UUID | Required | Identifier of the Plan active during this period. |
startDate | Date | Required | The start date of this billing period. |
endDate | Date | Required | The end date of this billing period. |
invoiceId | UUID | Optional | Identifier of the invoice created for this period's charge. |
paymentId | UUID | Optional | Identifier of the payment that settled the invoice for this period. |
status | string | Required | Status specific to this period (reflects invoicing/payment state). |
amountBilled | decimal | Optional | The actual amount billed for this period (could differ from plan due to promotions, usage, etc.). |
currency | string | Optional | Currency of the billed amount. |
createdAt | DateTime | Required | Timestamp when this period record was created (often at the start of the period). |
Relationships
- Subscription: A subscription period belongs to one
Subscription. - Plan: Reflects the
Planactive during this period. - Invoice: May be associated with one
Invoicegenerated for this period. - Payment: May be associated with one
Paymentthat settled the period’s invoice.
Examples
- Period for Jane Doe’s ‘Pro Plan’ from 2024-05-01 to 2024-05-31, invoiced via #INV-00123, status Paid.
- Period for Acme Corp’s ‘Enterprise Plan’ from 2024-04-15 to 2024-05-14, status Billed, awaiting payment.
- The first period (trial) for a new subscription from 2024-05-20 to 2024-06-19, status Active, amountBilled $0.00.