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

import typing_extensions
import typing_extensions
import typing
from .order_source import OrderSourceParams
from .order_line_item import OrderLineItemParams
from .order_line_item_tax import OrderLineItemTaxParams
from .order_line_item_discount import OrderLineItemDiscountParams
from .order_service_charge import OrderServiceChargeParams
from .fulfillment import FulfillmentParams
from .order_return import OrderReturnParams
from .order_money_amounts import OrderMoneyAmountsParams
from .order_rounding_adjustment import OrderRoundingAdjustmentParams
from .tender import TenderParams
from .refund import RefundParams
from ..types.order_state import OrderState
from .money import MoneyParams
from .order_pricing_options import OrderPricingOptionsParams
from .order_reward import OrderRewardParams


class OrderParams(typing_extensions.TypedDict):
    """
    Contains all information related to a single order to process with Square,
    including line items that specify the products to purchase. `Order` objects also
    include information about any associated tenders, refunds, and returns.

    All Connect V2 Transactions have all been converted to Orders including all associated
    itemization data.
    """

    id: typing_extensions.NotRequired[str]
    """
    The order's unique ID.
    """

    location_id: str
    """
    The ID of the seller location that this order is associated with.
    """

    reference_id: typing_extensions.NotRequired[typing.Optional[str]]
    """
    A client-specified ID to associate an entity in another system
    with this order.
    """

    source: typing_extensions.NotRequired[OrderSourceParams]
    """
    The origination details of the order.
    """

    customer_id: typing_extensions.NotRequired[typing.Optional[str]]
    """
    The ID of the [customer](entity:Customer) associated with the order.
    
    You should specify a `customer_id` on the order (or the payment) to ensure that transactions
    are reliably linked to customers. Omitting this field might result in the creation of new
    [instant profiles](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles).
    """

    line_items: typing_extensions.NotRequired[typing.Optional[typing.Sequence[OrderLineItemParams]]]
    """
    The line items included in the order.
    """

    taxes: typing_extensions.NotRequired[typing.Optional[typing.Sequence[OrderLineItemTaxParams]]]
    """
    The list of all taxes associated with the order.
    
    Taxes can be scoped to either `ORDER` or `LINE_ITEM`. For taxes with `LINE_ITEM` scope, an
    `OrderLineItemAppliedTax` must be added to each line item that the tax applies to. For taxes
    with `ORDER` scope, the server generates an `OrderLineItemAppliedTax` for every line item.
    
    On reads, each tax in the list includes the total amount of that tax applied to the order.
    
    __IMPORTANT__: If `LINE_ITEM` scope is set on any taxes in this field, using the deprecated
    `line_items.taxes` field results in an error. Use `line_items.applied_taxes`
    instead.
    """

    discounts: typing_extensions.NotRequired[typing.Optional[typing.Sequence[OrderLineItemDiscountParams]]]
    """
    The list of all discounts associated with the order.
    
    Discounts can be scoped to either `ORDER` or `LINE_ITEM`. For discounts scoped to `LINE_ITEM`,
    an `OrderLineItemAppliedDiscount` must be added to each line item that the discount applies to.
    For discounts with `ORDER` scope, the server generates an `OrderLineItemAppliedDiscount`
    for every line item.
    
    __IMPORTANT__: If `LINE_ITEM` scope is set on any discounts in this field, using the deprecated
    `line_items.discounts` field results in an error. Use `line_items.applied_discounts`
    instead.
    """

    service_charges: typing_extensions.NotRequired[typing.Optional[typing.Sequence[OrderServiceChargeParams]]]
    """
    A list of service charges applied to the order.
    """

    fulfillments: typing_extensions.NotRequired[typing.Optional[typing.Sequence[FulfillmentParams]]]
    """
    Details about order fulfillment.
    
    Orders can only be created with at most one fulfillment. However, orders returned
    by the API might contain multiple fulfillments.
    """

    returns: typing_extensions.NotRequired[typing.Sequence[OrderReturnParams]]
    """
    A collection of items from sale orders being returned in this one. Normally part of an
    itemized return or exchange. There is exactly one `Return` object per sale `Order` being
    referenced.
    """

    return_amounts: typing_extensions.NotRequired[OrderMoneyAmountsParams]
    """
    The rollup of the returned money amounts.
    """

    net_amounts: typing_extensions.NotRequired[OrderMoneyAmountsParams]
    """
    The net money amounts (sale money - return money).
    """

    rounding_adjustment: typing_extensions.NotRequired[OrderRoundingAdjustmentParams]
    """
    A positive rounding adjustment to the total of the order. This adjustment is commonly
    used to apply cash rounding when the minimum unit of account is smaller than the lowest physical
    denomination of the currency.
    """

    tenders: typing_extensions.NotRequired[typing.Sequence[TenderParams]]
    """
    The tenders that were used to pay for the order.
    """

    refunds: typing_extensions.NotRequired[typing.Sequence[RefundParams]]
    """
    The refunds that are part of this order.
    """

    metadata: typing_extensions.NotRequired[typing.Optional[typing.Dict[str, typing.Optional[str]]]]
    """
    Application-defined data attached to this order. Metadata fields are intended
    to store descriptive references or associations with an entity in another system or store brief
    information about the object. Square does not process this field; it only stores and returns it
    in relevant API calls. Do not use metadata to store any sensitive information (such as personally
    identifiable information or card details).
    
    Keys written by applications must be 60 characters or less and must be in the character set
    `[a-zA-Z0-9_-]`. Entries can also include metadata generated by Square. These keys are prefixed
    with a namespace, separated from the key with a ':' character.
    
    Values have a maximum length of 255 characters.
    
    An application can have up to 10 entries per metadata field.
    
    Entries written by applications are private and can only be read or modified by the same
    application.
    
    For more information, see  [Metadata](https://developer.squareup.com/docs/build-basics/metadata).
    """

    created_at: typing_extensions.NotRequired[str]
    """
    The timestamp for when the order was created, at server side, in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").
    """

    updated_at: typing_extensions.NotRequired[str]
    """
    The timestamp for when the order was last updated, at server side, in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").
    """

    closed_at: typing_extensions.NotRequired[str]
    """
    The timestamp for when the order reached a terminal [state](entity:OrderState), in RFC 3339 format (for example "2016-09-04T23:59:33.123Z").
    """

    state: typing_extensions.NotRequired[OrderState]
    """
    The current state of the order.
    See [OrderState](#type-orderstate) for possible values
    """

    version: typing_extensions.NotRequired[int]
    """
    The version number, which is incremented each time an update is committed to the order.
    Orders not created through the API do not include a version number and
    therefore cannot be updated.
    
    [Read more about working with versions](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders).
    """

    total_money: typing_extensions.NotRequired[MoneyParams]
    """
    The total amount of money to collect for the order.
    """

    total_tax_money: typing_extensions.NotRequired[MoneyParams]
    """
    The total amount of tax money to collect for the order.
    """

    total_discount_money: typing_extensions.NotRequired[MoneyParams]
    """
    The total amount of discount money to collect for the order.
    """

    total_tip_money: typing_extensions.NotRequired[MoneyParams]
    """
    The total amount of tip money to collect for the order.
    """

    total_service_charge_money: typing_extensions.NotRequired[MoneyParams]
    """
    The total amount of money collected in service charges for the order.
    
    Note: `total_service_charge_money` is the sum of `applied_money` fields for each individual
    service charge. Therefore, `total_service_charge_money` only includes inclusive tax amounts,
    not additive tax amounts.
    """

    ticket_name: typing_extensions.NotRequired[typing.Optional[str]]
    """
    A short-term identifier for the order (such as a customer first name,
    table number, or auto-generated order number that resets daily).
    """

    pricing_options: typing_extensions.NotRequired[OrderPricingOptionsParams]
    """
    Pricing options for an order. The options affect how the order's price is calculated.
    They can be used, for example, to apply automatic price adjustments that are based on
    preconfigured [pricing rules](entity:CatalogPricingRule).
    """

    rewards: typing_extensions.NotRequired[typing.Sequence[OrderRewardParams]]
    """
    A set-like list of Rewards that have been added to the Order.
    """

    net_amount_due_money: typing_extensions.NotRequired[MoneyParams]
    """
    The net amount of money due on the order.
    """
