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

from ..core.unchecked_base_model import UncheckedBaseModel
import typing
import pydantic
from .loyalty_promotion_incentive import LoyaltyPromotionIncentive
from .loyalty_promotion_available_time_data import LoyaltyPromotionAvailableTimeData
from .loyalty_promotion_trigger_limit import LoyaltyPromotionTriggerLimit
from .loyalty_promotion_status import LoyaltyPromotionStatus
from .money import Money
from ..core.pydantic_utilities import IS_PYDANTIC_V2


class LoyaltyPromotion(UncheckedBaseModel):
    """
    Represents a promotion for a [loyalty program](entity:LoyaltyProgram). Loyalty promotions enable buyers
    to earn extra points on top of those earned from the base program.

    A loyalty program can have a maximum of 10 loyalty promotions with an `ACTIVE` or `SCHEDULED` status.
    """

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

    name: str = pydantic.Field()
    """
    The name of the promotion.
    """

    incentive: LoyaltyPromotionIncentive = pydantic.Field()
    """
    The points incentive for the promotion. This field defines whether promotion points
    are earned by multiplying base program points or by adding a specified number of points.
    """

    available_time: LoyaltyPromotionAvailableTimeData = pydantic.Field()
    """
    The scheduling information that defines when purchases can qualify to earn points from an `ACTIVE` promotion.
    """

    trigger_limit: typing.Optional[LoyaltyPromotionTriggerLimit] = pydantic.Field(default=None)
    """
    The number of times a buyer can earn promotion points during a specified interval.
    If not specified, buyers can trigger the promotion an unlimited number of times.
    """

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

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

    canceled_at: typing.Optional[str] = pydantic.Field(default=None)
    """
    The timestamp of when the promotion was canceled, in RFC 3339 format.
    """

    updated_at: typing.Optional[str] = pydantic.Field(default=None)
    """
    The timestamp when the promotion was last updated, in RFC 3339 format.
    """

    loyalty_program_id: typing.Optional[str] = pydantic.Field(default=None)
    """
    The ID of the [loyalty program](entity:LoyaltyProgram) associated with the promotion.
    """

    minimum_spend_amount_money: typing.Optional[Money] = pydantic.Field(default=None)
    """
    The minimum purchase amount required to earn promotion points. If specified, this amount is positive.
    """

    qualifying_item_variation_ids: typing.Optional[typing.List[str]] = pydantic.Field(default=None)
    """
    The IDs of any qualifying `ITEM_VARIATION` [catalog objects](entity:CatalogObject). If specified,
    the purchase must include at least one of these items to qualify for the promotion.
    
    This option is valid only if the base loyalty program uses a `VISIT` or `SPEND` accrual rule.
    With `SPEND` accrual rules, make sure that qualifying promotional items are not excluded.
    
    You can specify `qualifying_item_variation_ids` or `qualifying_category_ids` for a given promotion, but not both.
    """

    qualifying_category_ids: typing.Optional[typing.List[str]] = pydantic.Field(default=None)
    """
    The IDs of any qualifying `CATEGORY` [catalog objects](entity:CatalogObject). If specified,
    the purchase must include at least one item from one of these categories to qualify for the promotion.
    
    This option is valid only if the base loyalty program uses a `VISIT` or `SPEND` accrual rule.
    With `SPEND` accrual rules, make sure that qualifying promotional items are not excluded.
    
    You can specify `qualifying_category_ids` or `qualifying_item_variation_ids` for a promotion, but not both.
    """

    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
