entity

SubscriptionPeriod

Represents a single billing cycle or interval within a subscription's lifetime.

Entity

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
subscriptionPeriodIdUUID Required Unique identifier for this specific subscription period.
subscriptionIdUUID Required Identifier of the parent Subscription this period belongs to.
planIdUUID Required Identifier of the Plan active during this period
startDateDate Required The start date of this billing period.
endDateDate Required The end date of this billing period.
invoiceIdUUID Optional Identifier of the invoice created for this period's charge.
paymentIdUUID Optional Identifier of the payment that settled the invoice for this period.
statusstring Required Status specific to this period (reflects invoicing/payment state).
amountBilleddecimal Optional The actual amount billed for this period (could differ from plan due to promotions, usage, etc.).
currencystring Optional Currency of the billed amount.
createdAtDateTime 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 Plan active during this period.
  • Invoice: May be associated with one Invoice generated for this period.
  • Payment: May be associated with one Payment that 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.
Edit this page