# This file was auto-generated by Fern from our API Definition.

from ..core.unchecked_base_model import UncheckedBaseModel
import typing
import pydantic
from .subscription_status import SubscriptionStatus
from .money import Money
from .subscription_source import SubscriptionSource
from .subscription_action import SubscriptionAction
from .phase import Phase
from ..core.pydantic_utilities import IS_PYDANTIC_V2


class Subscription(UncheckedBaseModel):
    """
    Represents a subscription purchased by a customer.

    For more information, see
    [Manage Subscriptions](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions).
    """

    id: typing.Optional[str] = pydantic.Field(default=None)
    """
    The Square-assigned ID of the subscription.
    """

    location_id: typing.Optional[str] = pydantic.Field(default=None)
    """
    The ID of the location associated with the subscription.
    """

    plan_variation_id: typing.Optional[str] = pydantic.Field(default=None)
    """
    The ID of the subscribed-to [subscription plan variation](entity:CatalogSubscriptionPlanVariation).
    """

    customer_id: typing.Optional[str] = pydantic.Field(default=None)
    """
    The ID of the subscribing [customer](entity:Customer) profile.
    """

    start_date: typing.Optional[str] = pydantic.Field(default=None)
    """
    The `YYYY-MM-DD`-formatted date (for example, 2013-01-15) to start the subscription.
    """

    canceled_date: typing.Optional[str] = pydantic.Field(default=None)
    """
    The `YYYY-MM-DD`-formatted date (for example, 2013-01-15) to cancel the subscription, 
    when the subscription status changes to `CANCELED` and the subscription billing stops.
    
    If this field is not set, the subscription ends according its subscription plan.
    
    This field cannot be updated, other than being cleared.
    """

    charged_through_date: typing.Optional[str] = pydantic.Field(default=None)
    """
    The `YYYY-MM-DD`-formatted date up to when the subscriber is invoiced for the
    subscription.
    
    After the invoice is sent for a given billing period,
    this date will be the last day of the billing period.
    For example,
    suppose for the month of May a subscriber gets an invoice
    (or charged the card) on May 1. For the monthly billing scenario,
    this date is then set to May 31.
    """

    status: typing.Optional[SubscriptionStatus] = pydantic.Field(default=None)
    """
    The current status of the subscription.
    See [SubscriptionStatus](#type-subscriptionstatus) for possible values
    """

    tax_percentage: typing.Optional[str] = pydantic.Field(default=None)
    """
    The tax amount applied when billing the subscription. The
    percentage is expressed in decimal form, using a `'.'` as the decimal
    separator and without a `'%'` sign. For example, a value of `7.5`
    corresponds to 7.5%.
    """

    invoice_ids: typing.Optional[typing.List[str]] = pydantic.Field(default=None)
    """
    The IDs of the [invoices](entity:Invoice) created for the
    subscription, listed in order when the invoices were created
    (newest invoices appear first).
    """

    price_override_money: typing.Optional[Money] = pydantic.Field(default=None)
    """
    A custom price which overrides the cost of a subscription plan variation with `STATIC` pricing.
    This field does not affect itemized subscriptions with `RELATIVE` pricing. Instead, 
    you should edit the Subscription's [order template](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions#phases-and-order-templates).
    """

    version: typing.Optional[int] = pydantic.Field(default=None)
    """
    The version of the object. When updating an object, the version
    supplied must match the version in the database, otherwise the write will
    be rejected as conflicting.
    """

    created_at: typing.Optional[str] = pydantic.Field(default=None)
    """
    The timestamp when the subscription was created, in RFC 3339 format.
    """

    card_id: typing.Optional[str] = pydantic.Field(default=None)
    """
    The ID of the [subscriber's](entity:Customer) [card](entity:Card)
    used to charge for the subscription.
    """

    timezone: typing.Optional[str] = pydantic.Field(default=None)
    """
    Timezone that will be used in date calculations for the subscription.
    Defaults to the timezone of the location based on `location_id`.
    Format: the IANA Timezone Database identifier for the location timezone (for example, `America/Los_Angeles`).
    """

    source: typing.Optional[SubscriptionSource] = pydantic.Field(default=None)
    """
    The origination details of the subscription.
    """

    actions: typing.Optional[typing.List[SubscriptionAction]] = pydantic.Field(default=None)
    """
    The list of scheduled actions on this subscription. It is set only in the response from  
    [RetrieveSubscription](api-endpoint:Subscriptions-RetrieveSubscription) with the query parameter
    of `include=actions` or from 
    [SearchSubscriptions](api-endpoint:Subscriptions-SearchSubscriptions) with the input parameter 
    of `include:["actions"]`.
    """

    monthly_billing_anchor_date: typing.Optional[int] = pydantic.Field(default=None)
    """
    The day of the month on which the subscription will issue invoices and publish orders.
    """

    phases: typing.Optional[typing.List[Phase]] = pydantic.Field(default=None)
    """
    array of phases for this subscription
    """

    if IS_PYDANTIC_V2:
        model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow", frozen=True)  # type: ignore # Pydantic v2
    else:

        class Config:
            frozen = True
            smart_union = True
            extra = pydantic.Extra.allow
