openapi: 3.0.0
info:
  version: '2.0'
  title: Square
  description: >-
    Supercharge Square for sellers of every size. Our entire connected commerce
    platform  from elegant hardware to a rich suite of Square APIs  is yours to
    build with. Whether youre developing an app or composing a bespoke solution,
    this is the place to make it happen. 
  termsOfService: https://connect.squareup.com/tos
  contact:
    name: Square Developer Platform
    email: developers@squareup.com
    url: https://squareup.com/developers
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  externalDocs:
    description: 'Read the official documentation here:'
    url: https://docs.connect.squareup.com/
  x-server-configuration:
    default-environment: production
    default-server: default
    environments:
      - name: production
        servers:
          - name: default
            url: https://connect.squareup.com
      - name: sandbox
        servers:
          - name: default
            url: https://connect.squareupsandbox.com
      - name: custom
        servers:
          - name: default
            url: '{custom_url}'
    parameters:
      - name: custom_url
        description: >-
          Sets the base URL requests are made to. Defaults to
          `https://connect.squareup.com`
        type: string
        example: https://connect.squareup.com
  x-square-generic-error-codes:
    - ACCESS_TOKEN_EXPIRED
    - ACCESS_TOKEN_REVOKED
    - API_VERSION_INCOMPATIBLE
    - APPLICATION_DISABLED
    - ARRAY_EMPTY
    - ARRAY_LENGTH_TOO_LONG
    - ARRAY_LENGTH_TOO_SHORT
    - BAD_CERTIFICATE
    - BAD_GATEWAY
    - BAD_REQUEST
    - CONFLICT
    - CONFLICTING_PARAMETERS
    - CURRENCY_MISMATCH
    - EXPECTED_ARRAY
    - EXPECTED_BASE64_ENCODED_BYTE_ARRAY
    - EXPECTED_BOOLEAN
    - EXPECTED_FLOAT
    - EXPECTED_INTEGER
    - EXPECTED_JSON_BODY
    - EXPECTED_MAP
    - EXPECTED_OBJECT
    - EXPECTED_STRING
    - FORBIDDEN
    - GATEWAY_TIMEOUT
    - GONE
    - IDEMPOTENCY_KEY_REUSED
    - INCORRECT_TYPE
    - INSUFFICIENT_SCOPES
    - INTERNAL_SERVER_ERROR
    - INVALID_ARRAY_VALUE
    - INVALID_CONTENT_TYPE
    - INVALID_CURSOR
    - INVALID_ENUM_VALUE
    - INVALID_FORM_VALUE
    - INVALID_SORT_ORDER
    - INVALID_SQUARE_VERSION_FORMAT
    - INVALID_TIME
    - INVALID_TIME_RANGE
    - INVALID_VALUE
    - LOCATION_MISMATCH
    - MAP_KEY_LENGTH_TOO_LONG
    - MAP_KEY_LENGTH_TOO_SHORT
    - MERCHANT_SUBSCRIPTION_NOT_FOUND
    - METHOD_NOT_ALLOWED
    - MISSING_REQUIRED_PARAMETER
    - NOT_ACCEPTABLE
    - NOT_FOUND
    - NOT_IMPLEMENTED
    - NO_FIELDS_SET
    - RATE_LIMITED
    - REQUEST_ENTITY_TOO_LARGE
    - REQUEST_TIMEOUT
    - SANDBOX_NOT_SUPPORTED
    - SERVICE_UNAVAILABLE
    - TOO_MANY_MAP_ENTRIES
    - UNAUTHORIZED
    - UNEXPECTED_VALUE
    - UNKNOWN_BODY_PARAMETER
    - UNKNOWN_QUERY_PARAMETER
    - UNPROCESSABLE_ENTITY
    - UNSUPPORTED_MEDIA_TYPE
    - V1_ACCESS_TOKEN
    - V1_APPLICATION
    - VALUE_EMPTY
    - VALUE_REGEX_MISMATCH
    - VALUE_TOO_HIGH
    - VALUE_TOO_LONG
    - VALUE_TOO_LOW
    - VALUE_TOO_SHORT
servers:
  - url: https://connect.squareup.com
    variables: {}
components:
  securitySchemes:
    oauth2:
      type: oauth2
      x-additional-headers:
        - name: Square-Version
          description: Square Connect API versions
          schema:
            default: '2025-01-23'
      flows:
        authorizationCode:
          authorizationUrl: https://connect.squareup.com/oauth2/authorize
          tokenUrl: https://connect.squareup.com/oauth2/token
          scopes:
            ADDON_CONFIGURATIONS_READ: >-
              __HTTP Method__: `GET`


              Grants write access for third-party Add-ons to read configurations
              of their Add-ons, for example, when calling
              `RetrieveConfiguration` endpoint.
            ADDON_CONFIGURATIONS_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access for third-party Add-ons to store
              configurations of their Add-ons, for example, when calling
              `CreateConfiguration` endpoint.
            APPOINTMENTS_ALL_READ: >-
              __HTTP Method__: `GET`, `POST`


              Grants read access to all of a seller's booking information,
              calendar, and business details.

              This permission must be accompanied by the `APPOINTMENTS_READ`
              permission.
            APPOINTMENTS_ALL_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to all booking details, including
              double-booking a seller.

              This permission must be accompanied by the `APPOINTMENTS_WRITE`
              permission.
            APPOINTMENTS_BUSINESS_SETTINGS_READ: >-
              __HTTP Method__: `GET`


              Grants read access to booking business settings. For example, to
              call the

              ListTeamMemberBookingProfiles endpoint.
            APPOINTMENTS_READ: >-
              __HTTP Method__: `GET`, `POST`


              Grants read access to booking information. For example, to call
              the

              RetrieveBooking endpoint.
            APPOINTMENTS_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to booking information. For example, to call
              the CreateBooking endpoint.
            BANK_ACCOUNTS_READ: >-
              __HTTP Method__: `GET`


              Grants read access to bank account information associated with the
              targeted

              Square account. For example, to call the Connect v1
              ListBankAccounts endpoint.
            CASH_DRAWER_READ: >-
              __HTTP Method__: `GET`


              Grants read access to cash drawer shift information. For example,
              to call the

              ListCashDrawerShifts endpoint.
            CHANNELS_CREATE: >-
              __HTTP Method__: `POST`


              Grants write access to create channels, for example, when calling
              the

              `CreateChannel` endpoint.
            CHANNELS_READ: |-
              __HTTP Method__: `GET`

              Grants read access to view channels, for example, when calling the
              `RetrieveChannel` endpoint.
            CHANNELS_UPDATE: >-
              __HTTP Method__: `PUT`


              Grants write access to update channels, for example, when calling
              the

              `UpdateChannel` endpoint.
            CUSTOMERS_READ: >-
              __HTTP Method__: `GET`


              Grants read access to customer information. For example, to call
              the

              ListCustomers endpoint.
            CUSTOMERS_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to customer information. For example, to
              create and update

              customer profiles.
            DEVICES_READ: |-
              __HTTP Method__: `GET`

              Grants read access to device information. For example, to
              call the `GetDevice` and `ListDevices` endpoints.
            DEVICE_CREDENTIAL_MANAGEMENT: >-
              __HTTP Method__: `POST`, `GET`


              Grants read/write access to device credentials information. For
              example, to

              call the CreateDeviceCode endpoint.
            DISPUTES_READ: >-
              __HTTP Method__: `GET`


              Grants read access to dispute information. For example, to call
              the RetrieveDispute

              endpoint.
            DISPUTES_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to dispute information. For example, to call
              the SubmitEvidence

              endpoint.
            EMPLOYEES_READ: >-
              __HTTP Method__: `GET`


              Grants read access to employee profile information. For example,
              to call the

              Connect v1 Employees API.
            EMPLOYEES_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to employee profile information. For example,
              to create

              and modify employee profiles.
            GIFTCARDS_READ: >-
              __HTTP Method__: `GET`, `POST`


              Grants read access to gift card information. For example, to call
              the RetrieveGiftCard

              endpoint.
            GIFTCARDS_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to gift card information. For example, to call
              the CreateGiftCard

              endpoint.
            INVENTORY_READ: >-
              __HTTP Method__: `GET`


              Grants read access to inventory information. For example, to call
              the

              RetrieveInventoryCount endpoint.
            INVENTORY_WRITE: >-
              __HTTP Method__:  `POST`, `PUT`, `DELETE`


              Grants write access to inventory information. For example, to call
              the

              BatchChangeInventory endpoint.
            INVOICES_READ: >-
              __HTTP Method__: `GET`, `POST`


              Grants read access to invoice information. For example, to call
              the ListInvoices endpoint.
            INVOICES_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to invoice information. For example, to call
              the CreateInvoice endpoint.
            ITEMS_READ: >-
              __HTTP Method__: `GET`


              Grants read access to product catalog information. For example, to
              obtain objects in a product catalog.
            ITEMS_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to product catalog information. For example,
              to modify or

              add to a product catalog.
            LOYALTY_READ: >-
              __HTTP Method__: `GET`


              Grants read access to loyalty information. For example, to call
              the

              ListLoyaltyPrograms endpoint.
            LOYALTY_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to loyalty information. For example, to call
              the

              CreateLoyaltyAccount endpoint.
            MERCHANT_PROFILE_READ: >-
              __HTTP Method__: `GET`


              Grants read access to business and location information. For
              example, to

              obtain a location ID for subsequent activity.
            MERCHANT_PROFILE_WRITE: >-
              __HTTP Method__: `POST`, `PUT`


              Grants write access to business and location information. For
              example, to create a new location or

              update the business hours at an existing location.
            ONLINE_STORE_SITE_READ: |-
              __HTTP Method__: `GET`, `POST`

              Read access to ECOM online store site details.
            ONLINE_STORE_SNIPPETS_READ: |-
              __HTTP Method__: `GET`, `POST`

              Read access to ECOM online store snippets on published websites.
            ONLINE_STORE_SNIPPETS_WRITE: |-
              __HTTP Method__: `POST`, `PUT`, `DELETE`

              Write access to ECOM online store snippets on published websites.
            ORDERS_READ: |-
              __HTTP Method__: `GET`

              Grants read access to order information. For example, to call the
              BatchRetrieveOrders endpoint.
            ORDERS_WRITE: |-
              __HTTP Method__: `POST`, `PUT`, `DELETE`

              Grants write access to order information. For example, to call the
              CreateCheckout endpoint.
            PAYMENTS_READ: >-
              __HTTP Method__: `GET`


              Grants read access to transaction and refund information. For
              example, to call

              the RetrieveTransaction endpoint.
            PAYMENTS_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to transaction and refunds information. For
              example, to

              process payments with the Payments or Checkout API.
            PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Allow third party applications to deduct a portion of each
              transaction amount.

              __Required__ to use multiparty transaction functionality with the
              Payments

              API.
            PAYMENTS_WRITE_IN_PERSON: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to payments and refunds information. For
              example, to

              process in-person payments.
            PAYMENTS_WRITE_SHARED_ONFILE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Allows the developer to process payments on behalf of a seller
              using a shared on file payment method.
            PAYOUTS_READ: >-
              __HTTP Method__: `GET`


              Grants read access to payouts and payout entries information. For
              example,

              to call the Connect v2 `ListPayouts` endpoint.
            PERMISSION_SETS_READ: >-
              __HTTP Method__: `GET`


              Grants read access to Permission Sets. For example, to

              call the `ListPermissionSets` and `RetrievePermissionSet`
              endpoints.
            PERMISSION_SETS_WRITE: |-
              __HTTP Method__: `PUT`

              Grants write access to Permission Sets.
            RESERVATIONS_READ: >-
              __HTTP Method__: `GET`


              Grants read access to reservation information, for example, when
              calling the

              `RetrieveReservation` endpoint.
            RESERVATIONS_WRITE: >-
              __HTTP Method__:  `POST`, `PUT`, `DELETE`


              Grants write access to reservation information, for example, when
              calling the

              `CreateReservation` endpoint.
            RESTAURANT_CHECKS_READ: >-
              __HTTP Method__: `GET`


              Grants read access to check information, for example, when calling
              the

              `RetrieveCheck` endpoint.
            SETTLEMENTS_READ: >-
              __HTTP Method__: `GET`


              Grants read access to settlement (deposit) information. For
              example, to call

              the Connect v1 ListSettlements endpoint.
            SUBSCRIPTIONS_READ: >-
              __HTTP Method__: `GET`, `POST`


              Grants read access to subscription information. For example, to
              call the RetrieveSubscription

              endpoint.
            SUBSCRIPTIONS_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to subscription information. For example, to
              call the CreateSubscription

              endpoint.
            TIMECARDS_READ: >-
              __HTTP Method__: `GET`


              Grants read access to employee timecard information. For example,
              to call the

              Connect v2 SearchShifts endpoint.
            TIMECARDS_SETTINGS_READ: >-
              __HTTP Method__: `GET`


              Grants read access to employee timecard settings information. For
              example, to

              call the GetBreakType endpoint.
            TIMECARDS_SETTINGS_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to employee timecard settings information. For
              example, to

              call the UpdateBreakType endpoint.
            TIMECARDS_WRITE: >-
              __HTTP Method__: `POST`, `PUT`, `DELETE`


              Grants write access to employee shift information. For example, to
              create

              and modify employee shifts.
            VENDOR_READ: >-
              __HTTP Method__: `GET`, `POST`


              Grants read access to vendor information, for example, when
              calling the

              `RetrieveVendor` endpoint.
            VENDOR_WRITE: >-
              __HTTP Method__:  `POST`, `PUT`, `DELETE`


              Grants write access to vendor information, for example, when
              calling the

              `BulkUpdateVendors` endpoint.
    oauth2ClientSecret:
      type: apiKey
      in: header
      name: Authorization
  schemas:
    ACHDetails:
      type: object
      description: >-
        ACH-specific details about `BANK_ACCOUNT` type payments with the
        `transfer_type` of `ACH`.
      x-release-status: PUBLIC
      properties:
        routing_number:
          type: string
          description: The routing number for the bank account.
          maxLength: 50
          nullable: true
        account_number_suffix:
          type: string
          description: The last few digits of the bank account number.
          minLength: 1
          maxLength: 4
          nullable: true
        account_type:
          type: string
          description: >-
            The type of the bank account performing the transfer. The account
            type can be `CHECKING`,

            `SAVINGS`, or `UNKNOWN`.
          maxLength: 50
          nullable: true
    AcceptDisputeRequest:
      type: object
      description: Defines the request parameters for the `AcceptDispute` endpoint.
      x-release-status: PUBLIC
      properties: {}
      example: {}
    AcceptDisputeResponse:
      type: object
      description: Defines the fields in an `AcceptDispute` response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        dispute:
          $ref: '#/components/schemas/Dispute'
          description: Details about the accepted dispute.
      example:
        dispute:
          amount_money:
            amount: 2500
            currency: USD
          brand_dispute_id: '100000809947'
          card_brand: VISA
          created_at: '2022-06-29T18:45:22.265Z'
          disputed_payment:
            payment_id: zhyh1ch64kRBrrlfVhwjCEjZWzNZY
          due_at: '2022-07-13T00:00:00.000Z'
          id: XDgyFu7yo1E2S5lQGGpYn
          location_id: L1HN3ZMQK64X9
          reason: NO_KNOWLEDGE
          reported_at: '2022-06-29T00:00:00.000Z'
          state: ACCEPTED
          updated_at: '2022-07-07T19:14:42.650Z'
          version: 2
    AcceptedPaymentMethods:
      type: object
      x-release-status: PUBLIC
      properties:
        apple_pay:
          type: boolean
          description: Whether Apple Pay is accepted at checkout.
          nullable: true
        google_pay:
          type: boolean
          description: Whether Google Pay is accepted at checkout.
          nullable: true
        cash_app_pay:
          type: boolean
          description: Whether Cash App Pay is accepted at checkout.
          nullable: true
        afterpay_clearpay:
          type: boolean
          description: Whether Afterpay/Clearpay is accepted at checkout.
          nullable: true
    AccumulateLoyaltyPointsRequest:
      type: object
      description: >-
        Represents an
        [AccumulateLoyaltyPoints](api-endpoint:Loyalty-AccumulateLoyaltyPoints)
        request.
      x-release-status: PUBLIC
      x-params-example: '?account_id=5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd'
      required:
        - accumulate_points
        - idempotency_key
        - location_id
      properties:
        accumulate_points:
          $ref: '#/components/schemas/LoyaltyEventAccumulatePoints'
          description: >-
            The points to add to the account. 

            If you are using the Orders API to manage orders, specify the order
            ID.

            Otherwise, specify the points to add.
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies the `AccumulateLoyaltyPoints`
            request. 

            Keys can be any valid string but must be unique for every request.
          minLength: 1
          maxLength: 128
        location_id:
          type: string
          description: The [location](entity:Location) where the purchase was made.
      example:
        accumulate_points:
          order_id: RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY
        idempotency_key: 58b90739-c3e8-4b11-85f7-e636d48d72cb
        location_id: P034NEENMD09F
    AccumulateLoyaltyPointsResponse:
      type: object
      description: >-
        Represents an
        [AccumulateLoyaltyPoints](api-endpoint:Loyalty-AccumulateLoyaltyPoints)
        response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        event:
          $ref: '#/components/schemas/LoyaltyEvent'
          description: >-
            The resulting loyalty event. Starting in Square version 2022-08-17,
            this field is no longer returned.
          x-release-status: DEPRECATED
        events:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyEvent'
          description: >-
            The resulting loyalty events. If the purchase qualifies for points,
            the `ACCUMULATE_POINTS` event

            is always included. When using the Orders API, the
            `ACCUMULATE_PROMOTION_POINTS` event is included

            if the purchase also qualifies for a loyalty promotion.
      example:
        events:
          - accumulate_points:
              loyalty_program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
              order_id: RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY
              points: 6
            created_at: '2020-05-08T21:41:12Z'
            id: ee46aafd-1af6-3695-a385-276e2ef0be26
            location_id: P034NEENMD09F
            loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
            source: LOYALTY_API
            type: ACCUMULATE_POINTS
    ActionCancelReason:
      type: string
      enum:
        - BUYER_CANCELED
        - SELLER_CANCELED
        - TIMED_OUT
      x-enum-elements:
        - name: BUYER_CANCELED
          description: A person canceled the `TerminalCheckout` from a Square device.
        - name: SELLER_CANCELED
          description: A client canceled the `TerminalCheckout` using the API.
        - name: TIMED_OUT
          description: >-
            The `TerminalCheckout` timed out (see `deadline_duration` on the
            `TerminalCheckout`).
      x-release-status: PUBLIC
    ActivityType:
      type: string
      enum:
        - ADJUSTMENT
        - APP_FEE_REFUND
        - APP_FEE_REVENUE
        - AUTOMATIC_SAVINGS
        - AUTOMATIC_SAVINGS_REVERSED
        - CHARGE
        - DEPOSIT_FEE
        - DEPOSIT_FEE_REVERSED
        - DISPUTE
        - ESCHEATMENT
        - FEE
        - FREE_PROCESSING
        - HOLD_ADJUSTMENT
        - INITIAL_BALANCE_CHANGE
        - MONEY_TRANSFER
        - MONEY_TRANSFER_REVERSAL
        - OPEN_DISPUTE
        - OTHER
        - OTHER_ADJUSTMENT
        - PAID_SERVICE_FEE
        - PAID_SERVICE_FEE_REFUND
        - REDEMPTION_CODE
        - REFUND
        - RELEASE_ADJUSTMENT
        - RESERVE_HOLD
        - RESERVE_RELEASE
        - RETURNED_PAYOUT
        - SQUARE_CAPITAL_PAYMENT
        - SQUARE_CAPITAL_REVERSED_PAYMENT
        - SUBSCRIPTION_FEE
        - SUBSCRIPTION_FEE_PAID_REFUND
        - SUBSCRIPTION_FEE_REFUND
        - TAX_ON_FEE
        - THIRD_PARTY_FEE
        - THIRD_PARTY_FEE_REFUND
        - PAYOUT
        - AUTOMATIC_BITCOIN_CONVERSIONS
        - AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED
        - CREDIT_CARD_REPAYMENT
        - CREDIT_CARD_REPAYMENT_REVERSED
        - LOCAL_OFFERS_CASHBACK
        - LOCAL_OFFERS_FEE
        - PERCENTAGE_PROCESSING_ENROLLMENT
        - PERCENTAGE_PROCESSING_DEACTIVATION
        - PERCENTAGE_PROCESSING_REPAYMENT
        - PERCENTAGE_PROCESSING_REPAYMENT_REVERSED
        - PROCESSING_FEE
        - PROCESSING_FEE_REFUND
        - UNDO_PROCESSING_FEE_REFUND
        - GIFT_CARD_LOAD_FEE
        - GIFT_CARD_LOAD_FEE_REFUND
        - UNDO_GIFT_CARD_LOAD_FEE_REFUND
        - BALANCE_FOLDERS_TRANSFER
        - BALANCE_FOLDERS_TRANSFER_REVERSED
        - GIFT_CARD_POOL_TRANSFER
        - GIFT_CARD_POOL_TRANSFER_REVERSED
        - SQUARE_PAYROLL_TRANSFER
        - SQUARE_PAYROLL_TRANSFER_REVERSED
      x-enum-elements:
        - name: ADJUSTMENT
          description: A manual adjustment applied to the seller's account by Square.
        - name: APP_FEE_REFUND
          description: A refund for an application fee on a payment.
        - name: APP_FEE_REVENUE
          description: Revenue generated from an application fee on a payment.
        - name: AUTOMATIC_SAVINGS
          description: >-
            An automatic transfer from the payment processing balance to the
            Square Savings account. These are generally proportional to the
            seller's sales.
        - name: AUTOMATIC_SAVINGS_REVERSED
          description: >-
            An automatic transfer from the Square Savings account back to the
            processing balance. These are generally proportional to the seller's
            refunds.
        - name: CHARGE
          description: A credit card payment capture.
        - name: DEPOSIT_FEE
          description: A fee assessed because of a deposit, such as an instant deposit.
        - name: DEPOSIT_FEE_REVERSED
          description: >-
            Indicates that Square returned a fee that was previously assessed
            because of a deposit, such as an instant deposit, back to the
            seller's account.
        - name: DISPUTE
          description: The balance change due to a dispute event.
        - name: ESCHEATMENT
          description: An escheatment entry for remittance.
        - name: FEE
          description: The cost plus adjustment fee.
        - name: FREE_PROCESSING
          description: >-
            Square offers free payments processing for a variety of business
            scenarios, including seller

            referrals or when Square wants to apologize (for example, for a bug,
            customer service, or repricing complication).

            This entry represents a credit to the seller for the purposes of
            free processing.
        - name: HOLD_ADJUSTMENT
          description: An adjustment made by Square related to holding a payment.
        - name: INITIAL_BALANCE_CHANGE
          description: >-
            An external change to a seller's balance (initial, in the sense that
            it causes the creation of the other activity types, such as a hold
            and refund).
        - name: MONEY_TRANSFER
          description: The balance change from a money transfer.
        - name: MONEY_TRANSFER_REVERSAL
          description: The reversal of a money transfer.
        - name: OPEN_DISPUTE
          description: The balance change for a chargeback that's been filed.
        - name: OTHER
          description: Any other type that doesn't belong in the rest of the types.
        - name: OTHER_ADJUSTMENT
          description: Any other type of adjustment that doesn't fall under existing types.
        - name: PAID_SERVICE_FEE
          description: A fee paid to a third-party seller.
        - name: PAID_SERVICE_FEE_REFUND
          description: A fee refunded to a third-party seller.
        - name: REDEMPTION_CODE
          description: Repayment for a redemption code.
        - name: REFUND
          description: A refund for an existing card payment.
        - name: RELEASE_ADJUSTMENT
          description: An adjustment made by Square related to releasing a payment.
        - name: RESERVE_HOLD
          description: Fees paid for a funding risk reserve.
        - name: RESERVE_RELEASE
          description: Fees released from a risk reserve.
        - name: RETURNED_PAYOUT
          description: >-
            An entry created when Square receives a response for the ACH file
            that Square sent indicating that the

            settlement of the original entry failed.
        - name: SQUARE_CAPITAL_PAYMENT
          description: >-
            A capital merchant cash advance (MCA) assessment. These are
            generally proportional to the merchant's sales but can be issued for
            other reasons related to the MCA.
        - name: SQUARE_CAPITAL_REVERSED_PAYMENT
          description: >-
            A capital merchant cash advance (MCA) assessment refund. These are
            generally proportional to the merchant's refunds but can be issued
            for other reasons related to the MCA.
        - name: SUBSCRIPTION_FEE
          description: A fee charged for subscription to a Square product.
        - name: SUBSCRIPTION_FEE_PAID_REFUND
          description: A Square subscription fee that's been refunded.
        - name: SUBSCRIPTION_FEE_REFUND
          description: The refund of a previously charged Square product subscription fee.
        - name: TAX_ON_FEE
          description: The tax paid on fee amounts.
        - name: THIRD_PARTY_FEE
          description: Fees collected by a third-party platform.
        - name: THIRD_PARTY_FEE_REFUND
          description: Refunded fees from a third-party platform.
        - name: PAYOUT
          description: >-
            The balance change due to a money transfer. Note that this type is
            never returned by the Payouts API.
        - name: AUTOMATIC_BITCOIN_CONVERSIONS
          description: >-
            Indicates that the portion of each payment withheld by Square was
            automatically converted into bitcoin using Cash App. The seller
            manages their bitcoin in their Cash App account.
        - name: AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED
          description: >-
            Indicates that a withheld payment, which was scheduled to be
            converted into bitcoin using Cash App, was deposited back to the
            Square payments balance.
        - name: CREDIT_CARD_REPAYMENT
          description: >-
            Indicates that a repayment toward the outstanding balance on the
            seller's Square credit card was made.
        - name: CREDIT_CARD_REPAYMENT_REVERSED
          description: >-
            Indicates that a repayment toward the outstanding balance on the
            seller's Square credit card was reversed.
        - name: LOCAL_OFFERS_CASHBACK
          description: >-
            Cashback amount given by a Square Local Offers seller to their
            customer for a purchase.
        - name: LOCAL_OFFERS_FEE
          description: >-
            A commission fee paid by a Square Local Offers seller to Square for
            a purchase discovered through Square Local Offers.
        - name: PERCENTAGE_PROCESSING_ENROLLMENT
          description: >-
            When activating Percentage Processing, a credit is applied to the
            sellers account to offset any negative balance caused by a dispute.
        - name: PERCENTAGE_PROCESSING_DEACTIVATION
          description: >-
            Deducting the outstanding Percentage Processing balance from the
            sellers account. It's the final installment in repaying the
            dispute-induced negative balance through percentage processing.
        - name: PERCENTAGE_PROCESSING_REPAYMENT
          description: >-
            Withheld funds from a payment to cover a negative balance. It's an
            installment to repay the amount from a dispute that had been offset
            during Percentage Processing enrollment.
        - name: PERCENTAGE_PROCESSING_REPAYMENT_REVERSED
          description: >-
            The reversal of a percentage processing repayment that happens for
            example when a refund is issued for a payment.
        - name: PROCESSING_FEE
          description: >-
            The processing fee for a payment. If sellers opt for Gross
            Settlement, i.e., direct bank withdrawal instead of deducting fees
            from daily sales, the processing fee is recorded separately as a new
            payout entry, not part of the CHARGE payout entry.
        - name: PROCESSING_FEE_REFUND
          description: >-
            The processing fee for a payment refund issued by sellers enrolled
            in Gross Settlement. The refunded processing fee is recorded
            separately as a new payout entry, not part of the REFUND payout
            entry.
        - name: UNDO_PROCESSING_FEE_REFUND
          description: >-
            When undoing a processing fee refund in a Gross Settlement payment,
            this payout entry type is used.
        - name: GIFT_CARD_LOAD_FEE
          description: >-
            Fee collected during the sale or reload of a gift card. This fee,
            which is a portion of the amount loaded on the gift card, is
            deducted from the merchant's payment balance.
        - name: GIFT_CARD_LOAD_FEE_REFUND
          description: Refund for fee charged during the sale or reload of a gift card.
        - name: UNDO_GIFT_CARD_LOAD_FEE_REFUND
          description: >-
            The undo of a refund for a fee charged during the sale or reload of
            a gift card.
        - name: BALANCE_FOLDERS_TRANSFER
          description: >-
            A transfer of funds to a banking folder. In the United States, the
            folder name is 'Checking Folder'; in Canada, it's 'Balance Folder.'
        - name: BALANCE_FOLDERS_TRANSFER_REVERSED
          description: >-
            A reversal of transfer of funds from a banking folder. In the United
            States, the folder name is 'Checking Folder'; in Canada, it's
            'Balance Folder.'
        - name: GIFT_CARD_POOL_TRANSFER
          description: >-
            A transfer of gift card funds to a central gift card pool account.
            In franchises, when gift cards are loaded or reloaded at any
            location, the money transfers to the franchisor's account.
        - name: GIFT_CARD_POOL_TRANSFER_REVERSED
          description: >-
            A reversal of transfer of gift card funds from a central gift card
            pool account. In franchises, when gift cards are loaded or reloaded
            at any location, the money transfers to the franchisor's account.
        - name: SQUARE_PAYROLL_TRANSFER
          description: >-
            A payroll payment that was transferred to a team members bank
            account.
        - name: SQUARE_PAYROLL_TRANSFER_REVERSED
          description: >-
            A payroll payment to a team members bank account that was deposited
            back to the sellers account by Square.
      x-release-status: PUBLIC
    AddGroupToCustomerRequest:
      type: object
      description: >-
        Defines the fields that are included in the request body of

        a request to the
        [AddGroupToCustomer](api-endpoint:Customers-AddGroupToCustomer)
        endpoint.
      x-release-status: PUBLIC
      properties: {}
      example: {}
    AddGroupToCustomerResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [AddGroupToCustomer](api-endpoint:Customers-AddGroupToCustomer)
        endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    AdditionalRecipient:
      type: object
      description: >-
        Represents an additional recipient (other than the merchant) receiving a
        portion of this tender.
      x-release-status: DEPRECATED
      required:
        - location_id
        - amount_money
      properties:
        location_id:
          type: string
          description: >-
            The location ID for a recipient (other than the merchant) receiving
            a portion of this tender.
          minLength: 1
          maxLength: 50
        description:
          type: string
          description: The description of the additional recipient.
          maxLength: 100
          nullable: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: The amount of money distributed to the recipient.
        receivable_id:
          type: string
          description: >-
            The unique ID for the RETIRED `AdditionalRecipientReceivable`
            object. This field should be empty for any `AdditionalRecipient`
            objects created after the retirement.
          maxLength: 192
          nullable: true
    Address:
      type: object
      description: >-
        Represents a postal address in a country. 

        For more information, see [Working with
        Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).
      x-release-status: PUBLIC
      properties:
        address_line_1:
          type: string
          description: >-
            The first line of the address.


            Fields that start with `address_line` provide the address's most
            specific

            details, like street number, street name, and building name. They do
            *not*

            provide less specific details like city, state/province, or country
            (these

            details are provided in other fields).
          nullable: true
        address_line_2:
          type: string
          description: The second line of the address, if any.
          nullable: true
        address_line_3:
          type: string
          description: The third line of the address, if any.
          nullable: true
        locality:
          type: string
          description: >-
            The city or town of the address. For a full list of field meanings
            by country, see [Working with
            Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).
          nullable: true
        sublocality:
          type: string
          description: A civil region within the address's `locality`, if any.
          nullable: true
        sublocality_2:
          type: string
          description: A civil region within the address's `sublocality`, if any.
          nullable: true
        sublocality_3:
          type: string
          description: A civil region within the address's `sublocality_2`, if any.
          nullable: true
        administrative_district_level_1:
          type: string
          description: >-
            A civil entity within the address's country. In the US, this

            is the state. For a full list of field meanings by country, see
            [Working with
            Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).
          nullable: true
        administrative_district_level_2:
          type: string
          description: >-
            A civil entity within the address's
            `administrative_district_level_1`.

            In the US, this is the county.
          nullable: true
        administrative_district_level_3:
          type: string
          description: >-
            A civil entity within the address's
            `administrative_district_level_2`,

            if any.
          nullable: true
        postal_code:
          type: string
          description: >-
            The address's postal code. For a full list of field meanings by
            country, see [Working with
            Addresses](https://developer.squareup.com/docs/build-basics/working-with-addresses).
          nullable: true
        country:
          $ref: '#/components/schemas/Country'
          description: >-
            The address's country, in the two-letter format of ISO 3166. For
            example, `US` or `FR`.

            See [Country](#type-country) for possible values
          nullable: true
        first_name:
          type: string
          description: Optional first name when it's representing recipient.
          nullable: true
        last_name:
          type: string
          description: Optional last name when it's representing recipient.
          nullable: true
    AdjustLoyaltyPointsRequest:
      type: object
      description: >-
        Represents an
        [AdjustLoyaltyPoints](api-endpoint:Loyalty-AdjustLoyaltyPoints) request.
      x-release-status: PUBLIC
      x-params-example: '?account_id=5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd'
      required:
        - idempotency_key
        - adjust_points
      properties:
        idempotency_key:
          type: string
          description: |-
            A unique string that identifies this `AdjustLoyaltyPoints` request. 
            Keys can be any valid string, but must be unique for every request.
          minLength: 1
          maxLength: 128
        adjust_points:
          $ref: '#/components/schemas/LoyaltyEventAdjustPoints'
          description: >-
            The points to add or subtract and the reason for the adjustment. To
            add points, specify a positive integer.

            To subtract points, specify a negative integer.
        allow_negative_balance:
          type: boolean
          description: >-
            Indicates whether to allow a negative adjustment to result in a
            negative balance. If `true`, a negative

            balance is allowed when subtracting points. If `false`, Square
            returns a `BAD_REQUEST` error when subtracting

            the specified number of points would result in a negative balance.
            The default value is `false`.
          nullable: true
      example:
        adjust_points:
          points: 10
          reason: Complimentary points
        idempotency_key: bc29a517-3dc9-450e-aa76-fae39ee849d1
    AdjustLoyaltyPointsResponse:
      type: object
      description: >-
        Represents an
        [AdjustLoyaltyPoints](api-endpoint:Loyalty-AdjustLoyaltyPoints) request.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        event:
          $ref: '#/components/schemas/LoyaltyEvent'
          description: The resulting event data for the adjustment.
      example:
        event:
          adjust_points:
            loyalty_program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
            points: 10
            reason: Complimentary points
          created_at: '2020-05-08T21:42:32Z'
          id: 613a6fca-8d67-39d0-bad2-3b4bc45c8637
          loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
          source: LOYALTY_API
          type: ADJUST_POINTS
    AfterpayDetails:
      type: object
      description: Additional details about Afterpay payments.
      x-release-status: PUBLIC
      properties:
        email_address:
          type: string
          description: Email address on the buyer's Afterpay account.
          maxLength: 255
          nullable: true
    ApplicationDetails:
      type: object
      description: Details about the application that took the payment.
      x-release-status: PUBLIC
      properties:
        square_product:
          $ref: '#/components/schemas/ApplicationDetailsExternalSquareProduct'
          description: >-
            The Square product, such as Square Point of Sale (POS), 

            Square Invoices, or Square Virtual Terminal.

            See [ExternalSquareProduct](#type-externalsquareproduct) for
            possible values
          nullable: true
        application_id:
          type: string
          description: >-
            The Square ID assigned to the application used to take the payment. 

            Application developers can use this information to identify payments
            that 

            their application processed. 

            For example, if a developer uses a custom application to process
            payments, 

            this field contains the application ID from the Developer
            Dashboard. 

            If a seller uses a [Square App
            Marketplace](https://developer.squareup.com/docs/app-marketplace) 

            application to process payments, the field contains the
            corresponding application ID.
          nullable: true
    ApplicationDetailsExternalSquareProduct:
      type: string
      enum:
        - APPOINTMENTS
        - ECOMMERCE_API
        - INVOICES
        - ONLINE_STORE
        - OTHER
        - RESTAURANTS
        - RETAIL
        - SQUARE_POS
        - TERMINAL_API
        - VIRTUAL_TERMINAL
      x-enum-elements:
        - name: APPOINTMENTS
          description: ''
        - name: ECOMMERCE_API
          description: ''
        - name: INVOICES
          description: ''
        - name: ONLINE_STORE
          description: ''
        - name: OTHER
          description: ''
        - name: RESTAURANTS
          description: ''
        - name: RETAIL
          description: ''
        - name: SQUARE_POS
          description: ''
        - name: TERMINAL_API
          description: ''
        - name: VIRTUAL_TERMINAL
          description: ''
      description: A list of products to return to external callers.
      x-release-status: PUBLIC
    ApplicationType:
      type: string
      enum:
        - TERMINAL_API
      x-enum-elements:
        - name: TERMINAL_API
          description: ''
      x-release-status: BETA
    AppointmentSegment:
      type: object
      description: Defines an appointment segment of a booking.
      x-release-status: PUBLIC
      required:
        - team_member_id
      properties:
        duration_minutes:
          type: integer
          description: The time span in minutes of an appointment segment.
          maximum: 1500
          nullable: true
        service_variation_id:
          type: string
          description: >-
            The ID of the [CatalogItemVariation](entity:CatalogItemVariation)
            object representing the service booked in this segment.
          maxLength: 36
          nullable: true
        team_member_id:
          type: string
          description: >-
            The ID of the [TeamMember](entity:TeamMember) object representing
            the team member booked in this segment.
          minLength: 1
          maxLength: 32
        service_variation_version:
          type: integer
          description: >-
            The current version of the item variation representing the service
            booked in this segment.
          format: int64
          nullable: true
        intermission_minutes:
          type: integer
          description: >-
            Time between the end of this segment and the beginning of the
            subsequent segment.
          readOnly: true
        any_team_member:
          type: boolean
          description: >-
            Whether the customer accepts any team member, instead of a specific
            one, to serve this segment.
          readOnly: true
        resource_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of the seller-accessible resources used for this appointment
            segment.
          readOnly: true
    ArchivedState:
      type: string
      enum:
        - ARCHIVED_STATE_NOT_ARCHIVED
        - ARCHIVED_STATE_ARCHIVED
        - ARCHIVED_STATE_ALL
      x-enum-elements:
        - name: ARCHIVED_STATE_NOT_ARCHIVED
          description: >-
            Requested items are not archived with the `is_archived` attribute
            set to `false`.
        - name: ARCHIVED_STATE_ARCHIVED
          description: >-
            Requested items are archived with the `is_archived` attribute set to
            `true`.
        - name: ARCHIVED_STATE_ALL
          description: Requested items can be archived or not archived.
      description: |-
        Defines the values for the `archived_state` query expression 
        used in [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) 
        to return the archived, not archived or either type of catalog items.
      x-release-status: PUBLIC
    Availability:
      type: object
      description: >-
        Defines an appointment slot that encapsulates the appointment segments,
        location and starting time available for booking.
      x-release-status: PUBLIC
      properties:
        start_at:
          type: string
          description: >-
            The RFC 3339 timestamp specifying the beginning time of the slot
            available for booking.
          nullable: true
        location_id:
          type: string
          description: The ID of the location available for booking.
          maxLength: 32
          readOnly: true
        appointment_segments:
          type: array
          items:
            $ref: '#/components/schemas/AppointmentSegment'
          description: The list of appointment segments available for booking
          nullable: true
    BankAccount:
      type: object
      description: >-
        Represents a bank account. For more information about 

        linking a bank account to a Square account, see 

        [Bank Accounts
        API](https://developer.squareup.com/docs/bank-accounts-api).
      x-release-status: PUBLIC
      required:
        - id
        - account_number_suffix
        - country
        - currency
        - account_type
        - holder_name
        - primary_bank_identification_number
        - status
        - creditable
        - debitable
      properties:
        id:
          type: string
          description: The unique, Square-issued identifier for the bank account.
          minLength: 1
          maxLength: 30
        account_number_suffix:
          type: string
          description: The last few digits of the account number.
          minLength: 1
        country:
          $ref: '#/components/schemas/Country'
          description: |-
            The ISO 3166 Alpha-2 country code where the bank account is based.
            See [Country](#type-country) for possible values
        currency:
          $ref: '#/components/schemas/Currency'
          description: >-
            The 3-character ISO 4217 currency code indicating the operating

            currency of the bank account. For example, the currency code for US
            dollars

            is `USD`.

            See [Currency](#type-currency) for possible values
        account_type:
          $ref: '#/components/schemas/BankAccountType'
          description: |-
            The financial purpose of the associated bank account.
            See [BankAccountType](#type-bankaccounttype) for possible values
        holder_name:
          type: string
          description: |-
            Name of the account holder. This name must match the name 
            on the targeted bank account record.
          minLength: 1
        primary_bank_identification_number:
          type: string
          description: >-
            Primary identifier for the bank. For more information, see 

            [Bank Accounts
            API](https://developer.squareup.com/docs/bank-accounts-api).
          maxLength: 40
        secondary_bank_identification_number:
          type: string
          description: >-
            Secondary identifier for the bank. For more information, see 

            [Bank Accounts
            API](https://developer.squareup.com/docs/bank-accounts-api).
          maxLength: 40
          nullable: true
        debit_mandate_reference_id:
          type: string
          description: >-
            Reference identifier that will be displayed to UK bank account
            owners

            when collecting direct debit authorization. Only required for UK
            bank accounts.
          nullable: true
        reference_id:
          type: string
          description: >-
            Client-provided identifier for linking the banking account to an
            entity

            in a third-party system (for example, a bank account number or a
            user identifier).
          nullable: true
        location_id:
          type: string
          description: The location to which the bank account belongs.
          nullable: true
        status:
          $ref: '#/components/schemas/BankAccountStatus'
          description: >-
            Read-only. The current verification status of this BankAccount
            object.

            See [BankAccountStatus](#type-bankaccountstatus) for possible values
        creditable:
          type: boolean
          description: >-
            Indicates whether it is possible for Square to send money to this
            bank account.
        debitable:
          type: boolean
          description: |-
            Indicates whether it is possible for Square to take money from this 
            bank account.
        fingerprint:
          type: string
          description: >-
            A Square-assigned, unique identifier for the bank account based on
            the

            account information. The account fingerprint can be used to compare
            account

            entries and determine if the they represent the same real-world bank
            account.
          nullable: true
        version:
          type: integer
          description: The current version of the `BankAccount`.
        bank_name:
          type: string
          description: |-
            Read only. Name of actual financial institution. 
            For example "Bank of America".
          maxLength: 100
          nullable: true
    BankAccountPaymentDetails:
      type: object
      description: Additional details about BANK_ACCOUNT type payments.
      x-release-status: PUBLIC
      properties:
        bank_name:
          type: string
          description: The name of the bank associated with the bank account.
          maxLength: 100
          nullable: true
        transfer_type:
          type: string
          description: The type of the bank transfer. The type can be `ACH` or `UNKNOWN`.
          maxLength: 50
          nullable: true
        account_ownership_type:
          type: string
          description: |-
            The ownership type of the bank account performing the transfer.
            The type can be `INDIVIDUAL`, `COMPANY`, or `ACCOUNT_TYPE_UNKNOWN`.
          maxLength: 50
          nullable: true
        fingerprint:
          type: string
          description: |-
            Uniquely identifies the bank account for this seller and can be used
            to determine if payments are from the same bank account.
          maxLength: 255
          nullable: true
        country:
          type: string
          description: >-
            The two-letter ISO code representing the country the bank account is
            located in.
          minLength: 2
          maxLength: 2
          nullable: true
        statement_description:
          type: string
          description: The statement description as sent to the bank.
          maxLength: 1000
          nullable: true
        ach_details:
          $ref: '#/components/schemas/ACHDetails'
          description: >-
            ACH-specific information about the transfer. The information is only
            populated

            if the `transfer_type` is `ACH`.
          nullable: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
          nullable: true
    BankAccountStatus:
      type: string
      enum:
        - VERIFICATION_IN_PROGRESS
        - VERIFIED
        - DISABLED
      x-enum-elements:
        - name: VERIFICATION_IN_PROGRESS
          description: >-
            Indicates that the verification process has started. Some features

            (for example, creditable or debitable) may be provisionally enabled
            on the bank

            account.
        - name: VERIFIED
          description: Indicates that the bank account was successfully verified.
        - name: DISABLED
          description: >-
            Indicates that the bank account is disabled and is permanently
            unusable

            for funds transfer. A bank account can be disabled because of a
            failed verification

            attempt or a failed deposit attempt.
      description: Indicates the current verification status of a `BankAccount` object.
      x-release-status: PUBLIC
    BankAccountType:
      type: string
      enum:
        - CHECKING
        - SAVINGS
        - INVESTMENT
        - OTHER
        - BUSINESS_CHECKING
      x-enum-elements:
        - name: CHECKING
          description: |-
            An account at a financial institution against which checks can be
            drawn by the account depositor.
        - name: SAVINGS
          description: >-
            An account at a financial institution that pays interest but cannot
            be

            used directly as money in the narrow sense of a medium of exchange.
        - name: INVESTMENT
          description: >-
            An account at a financial institution that contains a deposit of
            funds

            and/or securities.
        - name: OTHER
          description: >-
            An account at a financial institution which cannot be described by
            the

            other types.
        - name: BUSINESS_CHECKING
          description: |-
            An account at a financial institution against which checks can be
            drawn specifically for business purposes (non-personal use).
      description: Indicates the financial purpose of the bank account.
      x-release-status: PUBLIC
    BatchChangeInventoryRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - idempotency_key
      properties:
        idempotency_key:
          type: string
          description: >-
            A client-supplied, universally unique identifier (UUID) for the

            request.


            See
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
            in the

            [API Development
            101](https://developer.squareup.com/docs/buildbasics) section for
            more

            information.
          minLength: 1
          maxLength: 128
        changes:
          type: array
          items:
            $ref: '#/components/schemas/InventoryChange'
          description: >-
            The set of physical counts and inventory adjustments to be made.

            Changes are applied based on the client-supplied timestamp and may
            be sent

            out of order.
          nullable: true
        ignore_unchanged_counts:
          type: boolean
          description: >-
            Indicates whether the current physical count should be ignored if

            the quantity is unchanged since the last physical count. Default:
            `true`.
          nullable: true
      example:
        changes:
          - physical_count:
              catalog_object_id: W62UWFY35CWMYGVWK6TWJDNI
              location_id: C6W5YS5QM06F5
              occurred_at: '2016-11-16T22:25:24.878Z'
              quantity: '53'
              reference_id: 1536bfbf-efed-48bf-b17d-a197141b2a92
              state: IN_STOCK
              team_member_id: LRK57NSQ5X7PUD05
            type: PHYSICAL_COUNT
        idempotency_key: 8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe
        ignore_unchanged_counts: true
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.csharp
        java: >-
          /sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.java
        javascript: >-
          /sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.javascript
        php: >-
          /sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.php
        python: >-
          /sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.python
        ruby: >-
          /sdk_samples/Inventory/BatchChangeInventory/BatchChangeInventoryRequest.ruby
    BatchChangeInventoryResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        counts:
          type: array
          items:
            $ref: '#/components/schemas/InventoryCount'
          description: The current counts for all objects referenced in the request.
        changes:
          type: array
          items:
            $ref: '#/components/schemas/InventoryChange'
          description: Changes created for the request.
          x-release-status: BETA
      example:
        counts:
          - calculated_at: '2016-11-16T22:28:01.223Z'
            catalog_object_id: W62UWFY35CWMYGVWK6TWJDNI
            catalog_object_type: ITEM_VARIATION
            location_id: C6W5YS5QM06F5
            quantity: '53'
            state: IN_STOCK
        errors: []
    BatchDeleteCatalogObjectsRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        object_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of the CatalogObjects to be deleted. When an object is
            deleted, other objects

            in the graph that depend on that object will be deleted as well (for
            example, deleting a

            CatalogItem will delete its CatalogItemVariation.
          nullable: true
      example:
        object_ids:
          - W62UWFY35CWMYGVWK6TWJDNI
          - AA27W3M2GGTF3H6AVPNB77CK
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsRequest.csharp
        java: >-
          /sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsRequest.java
        javascript: >-
          /sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsRequest.javascript
        php: >-
          /sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsRequest.php
        python: >-
          /sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsRequest.python
        ruby: >-
          /sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsRequest.ruby
    BatchDeleteCatalogObjectsResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        deleted_object_ids:
          type: array
          items:
            type: string
          description: The IDs of all CatalogObjects deleted by this request.
        deleted_at:
          type: string
          description: >-
            The database
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)
            of this deletion in RFC 3339 format, e.g.,
            "2016-09-04T23:59:33.123Z".
      example:
        deleted_at: '2016-11-16T22:25:24.878Z'
        deleted_object_ids:
          - W62UWFY35CWMYGVWK6TWJDNI
          - AA27W3M2GGTF3H6AVPNB77CK
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsResponse.csharp
        java: >-
          /sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsResponse.java
        javascript: >-
          /sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsResponse.javascript
        php: >-
          /sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsResponse.php
        python: >-
          /sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsResponse.python
        ruby: >-
          /sdk_samples/Catalog/BatchDeleteCatalogObjects/BatchDeleteCatalogObjectsResponse.ruby
    BatchRetrieveCatalogObjectsRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - object_ids
      properties:
        object_ids:
          type: array
          items:
            type: string
          description: The IDs of the CatalogObjects to be retrieved.
        include_related_objects:
          type: boolean
          description: >-
            If `true`, the response will include additional objects that are
            related to the

            requested objects. Related objects are defined as any objects
            referenced by ID by the results in the `objects` field

            of the response. These objects are put in the `related_objects`
            field. Setting this to `true` is

            helpful when the objects are needed for immediate display to a user.

            This process only goes one level deep. Objects referenced by the
            related objects will not be included. For example,


            if the `objects` field of the response contains a CatalogItem, its
            associated

            CatalogCategory objects, CatalogTax objects, CatalogImage objects
            and

            CatalogModifierLists will be returned in the `related_objects` field
            of the

            response. If the `objects` field of the response contains a
            CatalogItemVariation,

            its parent CatalogItem will be returned in the `related_objects`
            field of

            the response.


            Default value: `false`
          nullable: true
        catalog_version:
          type: integer
          description: >-
            The specific version of the catalog objects to be included in the
            response. 

            This allows you to retrieve historical versions of objects. The
            specified version value is matched against

            the [CatalogObject](entity:CatalogObject)s' `version` attribute. If
            not included, results will

            be from the current version of the catalog.
          format: int64
          x-release-status: BETA
          nullable: true
        include_deleted_objects:
          type: boolean
          description: >-
            Indicates whether to include (`true`) or not (`false`) in the
            response deleted objects, namely, those with the `is_deleted`
            attribute set to `true`.
          nullable: true
        include_category_path_to_root:
          type: boolean
          description: >-
            Specifies whether or not to include the `path_to_root` list for each
            returned category instance. The `path_to_root` list consists

            of `CategoryPathToRootNode` objects and specifies the path that
            starts with the immediate parent category of the returned category

            and ends with its root category. If the returned category is a
            top-level category, the `path_to_root` list is empty and is not
            returned

            in the response payload.
          nullable: true
      example:
        include_related_objects: true
        object_ids:
          - W62UWFY35CWMYGVWK6TWJDNI
          - AA27W3M2GGTF3H6AVPNB77CK
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsRequest.csharp
        java: >-
          /sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsRequest.java
        javascript: >-
          /sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsRequest.javascript
        php: >-
          /sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsRequest.php
        python: >-
          /sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsRequest.python
        ruby: >-
          /sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsRequest.ruby
    BatchRetrieveCatalogObjectsResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        objects:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: A list of [CatalogObject](entity:CatalogObject)s returned.
        related_objects:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: >-
            A list of [CatalogObject](entity:CatalogObject)s referenced by the
            object in the `objects` field.
      example:
        objects:
          - id: W62UWFY35CWMYGVWK6TWJDNI
            is_deleted: false
            item_data:
              categories:
                - id: BJNQCF2FJ6S6UIDT65ABHLRX
                  ordinal: 0
              description: Hot Leaf Juice
              name: Tea
              tax_ids:
                - HURXQOOAIC4IZSI2BEXQRYFY
              variations:
                - id: 2TZFAOHWGG7PAK2QEXWYPZSP
                  is_deleted: false
                  item_variation_data:
                    item_id: W62UWFY35CWMYGVWK6TWJDNI
                    name: Mug
                    ordinal: 0
                    price_money:
                      amount: 150
                      currency: USD
                    pricing_type: FIXED_PRICING
                  present_at_all_locations: true
                  type: ITEM_VARIATION
                  updated_at: '2016-11-16T22:25:24.878Z'
                  version: 1479335124878
            present_at_all_locations: true
            type: ITEM
            updated_at: '2016-11-16T22:25:24.878Z'
            version: 1479335124878
          - id: AA27W3M2GGTF3H6AVPNB77CK
            is_deleted: false
            item_data:
              categories:
                - id: BJNQCF2FJ6S6UIDT65ABHLRX
                  ordinal: 0
              description: Hot Bean Juice
              name: Coffee
              tax_ids:
                - HURXQOOAIC4IZSI2BEXQRYFY
              variations:
                - id: LBTYIHNHU52WOIHWT7SNRIYH
                  is_deleted: false
                  item_variation_data:
                    item_id: AA27W3M2GGTF3H6AVPNB77CK
                    name: Regular
                    ordinal: 0
                    price_money:
                      amount: 250
                      currency: USD
                    pricing_type: FIXED_PRICING
                  present_at_all_locations: true
                  type: ITEM_VARIATION
                  updated_at: '2016-11-16T22:25:24.878Z'
                  version: 1479335124878
                - id: PKYIC7HGGKW5CYVSCVDEIMHY
                  is_deleted: false
                  item_variation_data:
                    item_id: AA27W3M2GGTF3H6AVPNB77CK
                    name: Large
                    ordinal: 1
                    price_money:
                      amount: 350
                      currency: USD
                    pricing_type: FIXED_PRICING
                  present_at_all_locations: true
                  type: ITEM_VARIATION
                  updated_at: '2016-11-16T22:25:24.878Z'
                  version: 1479335124878
            present_at_all_locations: true
            type: ITEM
            updated_at: '2016-11-16T22:25:24.878Z'
            version: 1479335124878
        related_objects:
          - category_data:
              name: Beverages
            id: BJNQCF2FJ6S6UIDT65ABHLRX
            is_deleted: false
            present_at_all_locations: true
            type: CATEGORY
            updated_at: '2016-11-16T22:25:24.878Z'
            version: 1479335124878
          - id: HURXQOOAIC4IZSI2BEXQRYFY
            is_deleted: false
            present_at_all_locations: true
            tax_data:
              calculation_phase: TAX_SUBTOTAL_PHASE
              enabled: true
              inclusion_type: ADDITIVE
              name: Sales Tax
              percentage: '5.0'
            type: TAX
            updated_at: '2016-11-16T22:25:24.878Z'
            version: 1479335124878
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsResponse.csharp
        java: >-
          /sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsResponse.java
        javascript: >-
          /sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsResponse.javascript
        php: >-
          /sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsResponse.php
        python: >-
          /sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsResponse.python
        ruby: >-
          /sdk_samples/Catalog/BatchRetrieveCatalogObjects/BatchRetrieveCatalogObjectsResponse.ruby
    BatchRetrieveInventoryChangesRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        catalog_object_ids:
          type: array
          items:
            type: string
          description: |-
            The filter to return results by `CatalogObject` ID.
            The filter is only applicable when set. The default value is null.
          nullable: true
        location_ids:
          type: array
          items:
            type: string
          description: |-
            The filter to return results by `Location` ID.
            The filter is only applicable when set. The default value is null.
          nullable: true
        types:
          type: array
          items:
            $ref: '#/components/schemas/InventoryChangeType'
          description: >-
            The filter to return results by `InventoryChangeType` values other
            than `TRANSFER`.

            The default value is `[PHYSICAL_COUNT, ADJUSTMENT]`.
          nullable: true
        states:
          type: array
          items:
            $ref: '#/components/schemas/InventoryState'
          description: |-
            The filter to return `ADJUSTMENT` query results by
            `InventoryState`. This filter is only applied when set.
            The default value is null.
          nullable: true
        updated_after:
          type: string
          description: |-
            The filter to return results with their `calculated_at` value
            after the given time as specified in an RFC 3339 timestamp.
            The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`).
          nullable: true
        updated_before:
          type: string
          description: >-
            The filter to return results with their `created_at` or
            `calculated_at` value

            strictly before the given time as specified in an RFC 3339
            timestamp.

            The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`).
          nullable: true
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for the original
            query.


            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
          nullable: true
        limit:
          type: integer
          description: The number of [records](entity:InventoryChange) to return.
          minimum: 1
          maximum: 1000
          nullable: true
      example:
        catalog_object_ids:
          - W62UWFY35CWMYGVWK6TWJDNI
        location_ids:
          - C6W5YS5QM06F5
        states:
          - IN_STOCK
        types:
          - PHYSICAL_COUNT
        updated_after: '2016-11-01T00:00:00.000Z'
        updated_before: '2016-12-01T00:00:00.000Z'
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Inventory/BatchRetrieveInventoryChanges/BatchRetrieveInventoryChangesRequest.csharp
        java: >-
          /sdk_samples/Inventory/BatchRetrieveInventoryChanges/BatchRetrieveInventoryChangesRequest.java
        javascript: >-
          /sdk_samples/Inventory/BatchRetrieveInventoryChanges/BatchRetrieveInventoryChangesRequest.javascript
        php: >-
          /sdk_samples/Inventory/BatchRetrieveInventoryChanges/BatchRetrieveInventoryChangesRequest.php
        python: >-
          /sdk_samples/Inventory/BatchRetrieveInventoryChanges/BatchRetrieveInventoryChangesRequest.python
        ruby: >-
          /sdk_samples/Inventory/BatchRetrieveInventoryChanges/BatchRetrieveInventoryChangesRequest.ruby
    BatchRetrieveInventoryChangesResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        changes:
          type: array
          items:
            $ref: '#/components/schemas/InventoryChange'
          description: |-
            The current calculated inventory changes for the requested objects
            and locations.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If unset,

            this is the final response.

            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
      example:
        changes:
          - physical_count:
              catalog_object_id: W62UWFY35CWMYGVWK6TWJDNI
              catalog_object_type: ITEM_VARIATION
              created_at: '2016-11-16T22:25:24.878Z'
              id: 46YDTW253DWGGK9HMAE6XCAO
              location_id: C6W5YS5QM06F5
              occurred_at: '2016-11-16T22:24:49.028Z'
              quantity: '86'
              reference_id: 22c07cf4-5626-4224-89f9-691112019399
              source:
                application_id: 416ff29c-86c4-4feb-b58c-9705f21f3ea0
                name: Square Point of Sale 4.37
                product: SQUARE_POS
              state: IN_STOCK
              team_member_id: LRK57NSQ5X7PUD05
            type: PHYSICAL_COUNT
        errors: []
    BatchRetrieveInventoryCountsRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        catalog_object_ids:
          type: array
          items:
            type: string
          description: |-
            The filter to return results by `CatalogObject` ID.
            The filter is applicable only when set.  The default is null.
          nullable: true
        location_ids:
          type: array
          items:
            type: string
          description: |-
            The filter to return results by `Location` ID.
            This filter is applicable only when set. The default is null.
          nullable: true
        updated_after:
          type: string
          description: |-
            The filter to return results with their `calculated_at` value
            after the given time as specified in an RFC 3339 timestamp.
            The default value is the UNIX epoch of (`1970-01-01T00:00:00Z`).
          nullable: true
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for the original
            query.


            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
          nullable: true
        states:
          type: array
          items:
            $ref: '#/components/schemas/InventoryState'
          description: >-
            The filter to return results by `InventoryState`. The filter is only
            applicable when set.

            Ignored are untracked states of `NONE`, `SOLD`, and
            `UNLINKED_RETURN`.

            The default is null.
          nullable: true
        limit:
          type: integer
          description: The number of [records](entity:InventoryCount) to return.
          minimum: 1
          maximum: 1000
          nullable: true
      example:
        catalog_object_ids:
          - W62UWFY35CWMYGVWK6TWJDNI
        location_ids:
          - 59TNP9SA8VGDA
        updated_after: '2016-11-16T00:00:00.000Z'
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Inventory/BatchRetrieveInventoryCounts/BatchRetrieveInventoryCountsRequest.csharp
        java: >-
          /sdk_samples/Inventory/BatchRetrieveInventoryCounts/BatchRetrieveInventoryCountsRequest.java
        javascript: >-
          /sdk_samples/Inventory/BatchRetrieveInventoryCounts/BatchRetrieveInventoryCountsRequest.javascript
        php: >-
          /sdk_samples/Inventory/BatchRetrieveInventoryCounts/BatchRetrieveInventoryCountsRequest.php
        python: >-
          /sdk_samples/Inventory/BatchRetrieveInventoryCounts/BatchRetrieveInventoryCountsRequest.python
        ruby: >-
          /sdk_samples/Inventory/BatchRetrieveInventoryCounts/BatchRetrieveInventoryCountsRequest.ruby
    BatchRetrieveInventoryCountsResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        counts:
          type: array
          items:
            $ref: '#/components/schemas/InventoryCount'
          description: |-
            The current calculated inventory counts for the requested objects
            and locations.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If unset,

            this is the final response.


            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
      example:
        counts:
          - calculated_at: '2016-11-16T22:28:01.223Z'
            catalog_object_id: W62UWFY35CWMYGVWK6TWJDNI
            catalog_object_type: ITEM_VARIATION
            location_id: 59TNP9SA8VGDA
            quantity: '79'
            state: IN_STOCK
        errors: []
    BatchRetrieveOrdersRequest:
      type: object
      description: |-
        Defines the fields that are included in requests to the
        `BatchRetrieveOrders` endpoint.
      x-release-status: PUBLIC
      required:
        - order_ids
      properties:
        location_id:
          type: string
          description: >-
            The ID of the location for these orders. This field is optional:
            omit it to retrieve

            orders within the scope of the current authorization's merchant ID.
          nullable: true
        order_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of the orders to retrieve. A maximum of 100 orders can be
            retrieved per request.
      example:
        location_id: 057P5VYJ4A5X1
        order_ids:
          - CAISEM82RcpmcFBM0TfOyiHV3es
          - CAISENgvlJ6jLWAzERDzjyHVybY
    BatchRetrieveOrdersResponse:
      type: object
      description: |-
        Defines the fields that are included in the response body of
        a request to the `BatchRetrieveOrders` endpoint.
      x-release-status: PUBLIC
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
          description: >-
            The requested orders. This will omit any requested orders that do
            not exist.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        orders:
          - id: CAISEM82RcpmcFBM0TfOyiHV3es
            line_items:
              - base_price_money:
                  amount: 1599
                  currency: USD
                name: Awesome product
                quantity: '1'
                total_money:
                  amount: 1599
                  currency: USD
                uid: 945986d1-9586-11e6-ad5a-28cfe92138cf
              - base_price_money:
                  amount: 2000
                  currency: USD
                name: Another awesome product
                quantity: '3'
                total_money:
                  amount: 6000
                  currency: USD
                uid: a8f4168c-9586-11e6-bdf0-28cfe92138cf
            location_id: 057P5VYJ4A5X1
            reference_id: my-order-001
            total_money:
              amount: 7599
              currency: USD
    BatchUpsertCatalogObjectsRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - idempotency_key
        - batches
      properties:
        idempotency_key:
          type: string
          description: >-
            A value you specify that uniquely identifies this

            request among all your requests. A common way to create

            a valid idempotency key is to use a Universally unique

            identifier (UUID).


            If you're unsure whether a particular request was successful,

            you can reattempt it with the same idempotency key without

            worrying about creating duplicate objects.


            See
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
            for more information.
          minLength: 1
          maxLength: 128
        batches:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObjectBatch'
          description: >-
            A batch of CatalogObjects to be inserted/updated atomically.

            The objects within a batch will be inserted in an all-or-nothing
            fashion, i.e., if an error occurs

            attempting to insert or update an object within a batch, the entire
            batch will be rejected. However, an error

            in one batch will not affect other batches within the same request.


            For each object, its `updated_at` field is ignored and replaced with
            a current
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates),
            and its

            `is_deleted` field must not be set to `true`.


            To modify an existing object, supply its ID. To create a new object,
            use an ID starting

            with `#`. These IDs may be used to create relationships between an
            object and attributes of

            other objects that reference it. For example, you can create a
            CatalogItem with

            ID `#ABC` and a CatalogItemVariation with its `item_id` attribute
            set to

            `#ABC` in order to associate the CatalogItemVariation with its
            parent

            CatalogItem.


            Any `#`-prefixed IDs are valid only within a single atomic batch,
            and will be replaced by server-generated IDs.


            Each batch may contain up to 1,000 objects. The total number of
            objects across all batches for a single request

            may not exceed 10,000. If either of these limits is violated, an
            error will be returned and no objects will

            be inserted or updated.
      example:
        batches:
          - objects:
              - id: '#Tea'
                item_data:
                  categories:
                    - id: '#Beverages'
                  description_html: <p><strong>Hot</strong> Leaf Juice</p>
                  name: Tea
                  tax_ids:
                    - '#SalesTax'
                  variations:
                    - id: '#Tea_Mug'
                      item_variation_data:
                        item_id: '#Tea'
                        name: Mug
                        price_money:
                          amount: 150
                          currency: USD
                        pricing_type: FIXED_PRICING
                      present_at_all_locations: true
                      type: ITEM_VARIATION
                present_at_all_locations: true
                type: ITEM
              - id: '#Coffee'
                item_data:
                  categories:
                    - id: '#Beverages'
                  description_html: <p>Hot <em>Bean Juice</em></p>
                  name: Coffee
                  tax_ids:
                    - '#SalesTax'
                  variations:
                    - id: '#Coffee_Regular'
                      item_variation_data:
                        item_id: '#Coffee'
                        name: Regular
                        price_money:
                          amount: 250
                          currency: USD
                        pricing_type: FIXED_PRICING
                      present_at_all_locations: true
                      type: ITEM_VARIATION
                    - id: '#Coffee_Large'
                      item_variation_data:
                        item_id: '#Coffee'
                        name: Large
                        price_money:
                          amount: 350
                          currency: USD
                        pricing_type: FIXED_PRICING
                      present_at_all_locations: true
                      type: ITEM_VARIATION
                present_at_all_locations: true
                type: ITEM
              - category_data:
                  name: Beverages
                id: '#Beverages'
                present_at_all_locations: true
                type: CATEGORY
              - id: '#SalesTax'
                present_at_all_locations: true
                tax_data:
                  applies_to_custom_amounts: true
                  calculation_phase: TAX_SUBTOTAL_PHASE
                  enabled: true
                  inclusion_type: ADDITIVE
                  name: Sales Tax
                  percentage: '5.0'
                type: TAX
        idempotency_key: 789ff020-f723-43a9-b4b5-43b5dc1fa3dc
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsRequest.csharp
        java: >-
          /sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsRequest.java
        javascript: >-
          /sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsRequest.javascript
        php: >-
          /sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsRequest.php
        python: >-
          /sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsRequest.python
        ruby: >-
          /sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsRequest.ruby
    BatchUpsertCatalogObjectsResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        objects:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: The created successfully created CatalogObjects.
        updated_at:
          type: string
          description: >-
            The database
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)
            of this update in RFC 3339 format, e.g., "2016-09-04T23:59:33.123Z".
        id_mappings:
          type: array
          items:
            $ref: '#/components/schemas/CatalogIdMapping'
          description: The mapping between client and server IDs for this upsert.
      example:
        id_mappings:
          - client_object_id: '#Tea'
            object_id: 67GA7XA2FWMRYY2VCONTYZJR
          - client_object_id: '#Coffee'
            object_id: MQ4TZKOG3SR2EQI3TWEK4AH7
          - client_object_id: '#Beverages'
            object_id: XCS4SCGN4WQYE2VU4U3TKXEH
          - client_object_id: '#SalesTax'
            object_id: HP5VNYPKZKTNCKZ2Z5NPUH6A
          - client_object_id: '#Tea_Mug'
            object_id: CAJBHUIQH7ONTSZI2KTVOUP6
          - client_object_id: '#Coffee_Regular'
            object_id: GY2GXJTVVPQAPW43GFRR3NG6
          - client_object_id: '#Coffee_Large'
            object_id: JE6VHPSRQL6IWSN26C36CJ7W
        objects:
          - created_at: '2023-11-30T19:24:35.4Z'
            id: 67GA7XA2FWMRYY2VCONTYZJR
            is_deleted: false
            item_data:
              categories:
                - id: XCS4SCGN4WQYE2VU4U3TKXEH
                  ordinal: -2251731094208512
              description: Hot Leaf Juice
              description_html: <p><strong>Hot</strong> Leaf Juice</p>
              description_plaintext: Hot Leaf Juice
              is_archived: false
              is_taxable: true
              name: Tea
              product_type: REGULAR
              tax_ids:
                - HP5VNYPKZKTNCKZ2Z5NPUH6A
              variations:
                - created_at: '2023-11-30T19:24:35.4Z'
                  id: CAJBHUIQH7ONTSZI2KTVOUP6
                  is_deleted: false
                  item_variation_data:
                    item_id: 67GA7XA2FWMRYY2VCONTYZJR
                    name: Mug
                    ordinal: 0
                    price_money:
                      amount: 150
                      currency: USD
                    pricing_type: FIXED_PRICING
                    sellable: true
                    stockable: true
                  present_at_all_locations: true
                  type: ITEM_VARIATION
                  updated_at: '2023-11-30T19:24:35.4Z'
                  version: 1701372275400
            present_at_all_locations: true
            type: ITEM
            updated_at: '2023-11-30T19:24:35.4Z'
            version: 1701372275400
          - created_at: '2023-11-30T19:24:35.4Z'
            id: MQ4TZKOG3SR2EQI3TWEK4AH7
            is_deleted: false
            item_data:
              categories:
                - id: XCS4SCGN4WQYE2VU4U3TKXEH
                  ordinal: -2251662374731776
              description: Hot Bean Juice
              description_html: <p>Hot <em>Bean Juice</em></p>
              description_plaintext: Hot Bean Juice
              is_archived: false
              is_taxable: true
              name: Coffee
              product_type: REGULAR
              tax_ids:
                - HP5VNYPKZKTNCKZ2Z5NPUH6A
              variations:
                - created_at: '2023-11-30T19:24:35.4Z'
                  id: GY2GXJTVVPQAPW43GFRR3NG6
                  is_deleted: false
                  item_variation_data:
                    item_id: MQ4TZKOG3SR2EQI3TWEK4AH7
                    name: Regular
                    ordinal: 0
                    price_money:
                      amount: 250
                      currency: USD
                    pricing_type: FIXED_PRICING
                    sellable: true
                    stockable: true
                  present_at_all_locations: true
                  type: ITEM_VARIATION
                  updated_at: '2023-11-30T19:24:35.4Z'
                  version: 1701372275400
                - created_at: '2023-11-30T19:24:35.4Z'
                  id: JE6VHPSRQL6IWSN26C36CJ7W
                  is_deleted: false
                  item_variation_data:
                    item_id: MQ4TZKOG3SR2EQI3TWEK4AH7
                    name: Large
                    ordinal: 1
                    price_money:
                      amount: 350
                      currency: USD
                    pricing_type: FIXED_PRICING
                    sellable: true
                    stockable: true
                  present_at_all_locations: true
                  type: ITEM_VARIATION
                  updated_at: '2023-11-30T19:24:35.4Z'
                  version: 1701372275400
            present_at_all_locations: true
            type: ITEM
            updated_at: '2023-11-30T19:24:35.4Z'
            version: 1701372275400
          - category_data:
              category_type: REGULAR_CATEGORY
              is_top_level: true
              name: Beverages
              online_visibility: true
              parent_category:
                ordinal: -2250837741010944
            created_at: '2023-11-30T19:24:35.4Z'
            id: XCS4SCGN4WQYE2VU4U3TKXEH
            is_deleted: false
            present_at_all_locations: true
            type: CATEGORY
            updated_at: '2023-11-30T19:24:35.4Z'
            version: 1701372275400
          - created_at: '2023-11-30T19:24:35.4Z'
            id: HP5VNYPKZKTNCKZ2Z5NPUH6A
            is_deleted: false
            present_at_all_locations: true
            tax_data:
              applies_to_custom_amounts: true
              calculation_phase: TAX_SUBTOTAL_PHASE
              enabled: true
              inclusion_type: ADDITIVE
              name: Sales Tax
              percentage: '5.0'
            type: TAX
            updated_at: '2023-11-30T19:24:35.4Z'
            version: 1701372275400
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsResponse.csharp
        java: >-
          /sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsResponse.java
        javascript: >-
          /sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsResponse.javascript
        php: >-
          /sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsResponse.php
        python: >-
          /sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsResponse.python
        ruby: >-
          /sdk_samples/Catalog/BatchUpsertCatalogObjects/BatchUpsertCatalogObjectsResponse.ruby
    Booking:
      type: object
      description: >-
        Represents a booking as a time-bound service contract for a seller's
        staff member to provide a specified service

        at a given location to a requesting customer in one or more appointment
        segments.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: A unique ID of this object representing a booking.
          maxLength: 36
          readOnly: true
        version:
          type: integer
          description: The revision number for the booking used for optimistic concurrency.
        status:
          $ref: '#/components/schemas/BookingStatus'
          description: >-
            The status of the booking, describing where the booking stands with
            respect to the booking state machine.

            See [BookingStatus](#type-bookingstatus) for possible values
          readOnly: true
        created_at:
          type: string
          description: The RFC 3339 timestamp specifying the creation time of this booking.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The RFC 3339 timestamp specifying the most recent update time of
            this booking.
          readOnly: true
        start_at:
          type: string
          description: The RFC 3339 timestamp specifying the starting time of this booking.
          nullable: true
        location_id:
          type: string
          description: >-
            The ID of the [Location](entity:Location) object representing the
            location where the booked service is provided. Once set when the
            booking is created, its value cannot be changed.
          maxLength: 32
          nullable: true
        customer_id:
          type: string
          description: >-
            The ID of the [Customer](entity:Customer) object representing the
            customer receiving the booked service.
          maxLength: 192
          nullable: true
        customer_note:
          type: string
          description: >-
            The free-text field for the customer to supply notes about the
            booking. For example, the note can be preferences that cannot be
            expressed by supported attributes of a relevant
            [CatalogObject](entity:CatalogObject) instance.
          maxLength: 4096
          nullable: true
        seller_note:
          type: string
          description: >-
            The free-text field for the seller to supply notes about the
            booking. For example, the note can be preferences that cannot be
            expressed by supported attributes of a specific
            [CatalogObject](entity:CatalogObject) instance.

            This field should not be visible to customers.
          maxLength: 4096
          nullable: true
        appointment_segments:
          type: array
          items:
            $ref: '#/components/schemas/AppointmentSegment'
          description: A list of appointment segments for this booking.
          nullable: true
        transition_time_minutes:
          type: integer
          description: >-
            Additional time at the end of a booking.

            Applications should not make this field visible to customers of a
            seller.
          readOnly: true
        all_day:
          type: boolean
          description: Whether the booking is of a full business day.
          readOnly: true
        location_type:
          $ref: '#/components/schemas/BusinessAppointmentSettingsBookingLocationType'
          description: >-
            The type of location where the booking is held.

            See
            [BusinessAppointmentSettingsBookingLocationType](#type-businessappointmentsettingsbookinglocationtype)
            for possible values
          nullable: true
        creator_details:
          $ref: '#/components/schemas/BookingCreatorDetails'
          description: Information about the booking creator.
          readOnly: true
        source:
          $ref: '#/components/schemas/BookingBookingSource'
          description: >-
            The source of the booking.

            Access to this field requires seller-level permissions.

            See [BookingBookingSource](#type-bookingbookingsource) for possible
            values
          readOnly: true
        address:
          $ref: '#/components/schemas/Address'
          description: >-
            Stores a customer address if the location type is
            `CUSTOMER_LOCATION`.
          nullable: true
    BookingBookingSource:
      type: string
      enum:
        - FIRST_PARTY_MERCHANT
        - FIRST_PARTY_BUYER
        - THIRD_PARTY_BUYER
        - API
      x-enum-elements:
        - name: FIRST_PARTY_MERCHANT
          description: >-
            The booking was created by a seller from a Square Appointments
            application, such as the Square Appointments Dashboard or a Square
            Appointments mobile app.
        - name: FIRST_PARTY_BUYER
          description: >-
            The booking was created by a buyer from a Square Appointments
            application, such as Square Online Booking Site.
        - name: THIRD_PARTY_BUYER
          description: >-
            The booking was created by a buyer created from a third-party
            application.
        - name: API
          description: >-
            The booking was created by a seller or a buyer from the Square
            Bookings API.
      description: Supported sources a booking was created from.
      x-release-status: PUBLIC
    BookingCreatorDetails:
      type: object
      description: Information about a booking creator.
      x-release-status: PUBLIC
      properties:
        creator_type:
          $ref: '#/components/schemas/BookingCreatorDetailsCreatorType'
          description: >-
            The seller-accessible type of the creator of the booking.

            See
            [BookingCreatorDetailsCreatorType](#type-bookingcreatordetailscreatortype)
            for possible values
          readOnly: true
        team_member_id:
          type: string
          description: >-
            The ID of the team member who created the booking, when the booking
            creator is of the `TEAM_MEMBER` type.

            Access to this field requires seller-level permissions.
          maxLength: 32
          readOnly: true
        customer_id:
          type: string
          description: >-
            The ID of the customer who created the booking, when the booking
            creator is of the `CUSTOMER` type.

            Access to this field requires seller-level permissions.
          maxLength: 192
          readOnly: true
    BookingCreatorDetailsCreatorType:
      type: string
      enum:
        - TEAM_MEMBER
        - CUSTOMER
      x-enum-elements:
        - name: TEAM_MEMBER
          description: The creator is of the seller type.
        - name: CUSTOMER
          description: The creator is of the buyer type.
      description: Supported types of a booking creator.
      x-release-status: PUBLIC
    BookingCustomAttributeDeleteRequest:
      type: object
      description: >-
        Represents an individual delete request in a
        [BulkDeleteBookingCustomAttributes](api-endpoint:BookingCustomAttributes-BulkDeleteBookingCustomAttributes)

        request. An individual request contains a booking ID, the custom
        attribute to delete, and an optional idempotency key.
      x-release-status: PUBLIC
      required:
        - booking_id
        - key
      properties:
        booking_id:
          type: string
          description: The ID of the target [booking](entity:Booking).
          minLength: 1
          maxLength: 36
        key:
          type: string
          description: >-
            The key of the custom attribute to delete. This key must match the
            `key` of a

            custom attribute definition in the Square seller account. If the
            requesting application is not

            the definition owner, you must use the qualified key.
          minLength: 1
    BookingCustomAttributeDeleteResponse:
      type: object
      description: >-
        Represents a response for an individual upsert request in a
        [BulkDeleteBookingCustomAttributes](api-endpoint:BookingCustomAttributes-BulkDeleteBookingCustomAttributes)
        operation.
      x-release-status: PUBLIC
      properties:
        booking_id:
          type: string
          description: >-
            The ID of the [booking](entity:Booking) associated with the custom
            attribute.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred while processing the individual request.
      example:
        booking_id: N3NCVYY3WS27HF0HKANA3R9FP8
        errors: []
    BookingCustomAttributeUpsertRequest:
      type: object
      description: >-
        Represents an individual upsert request in a
        [BulkUpsertBookingCustomAttributes](api-endpoint:BookingCustomAttributes-BulkUpsertBookingCustomAttributes)

        request. An individual request contains a booking ID, the custom
        attribute to create or update,

        and an optional idempotency key.
      x-release-status: PUBLIC
      required:
        - booking_id
        - custom_attribute
      properties:
        booking_id:
          type: string
          description: The ID of the target [booking](entity:Booking).
          minLength: 1
          maxLength: 36
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The custom attribute to create or update, with following fields:


            - `key`. This key must match the `key` of a custom attribute
            definition in the Square seller

            account. If the requesting application is not the definition owner,
            you must provide the qualified key.


            - `value`. This value must conform to the `schema` specified by the
            definition.

            For more information, see [Value data
            types](https://developer.squareup.com/docs/booking-custom-attributes-api/custom-attributes#value-data-types).


            - `version`. To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control for update operations, include this optional field in the
            request and set the

            value to the current version of the custom attribute.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this individual upsert request, used to
            ensure idempotency.

            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
          nullable: true
    BookingCustomAttributeUpsertResponse:
      type: object
      description: >-
        Represents a response for an individual upsert request in a
        [BulkUpsertBookingCustomAttributes](api-endpoint:BookingCustomAttributes-BulkUpsertBookingCustomAttributes)
        operation.
      x-release-status: PUBLIC
      properties:
        booking_id:
          type: string
          description: >-
            The ID of the [booking](entity:Booking) associated with the custom
            attribute.
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: The new or updated custom attribute.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred while processing the individual request.
      example:
        custom_attribute:
          created_at: '2022-11-16T00:14:47Z'
          key: favoriteShampoo
          updated_at: '2022-11-16T00:16:23Z'
          value: Spring Fresh
          version: 1
          visibility: VISIBILITY_READ_WRITE_VALUES
        errors: []
    BookingStatus:
      type: string
      enum:
        - PENDING
        - CANCELLED_BY_CUSTOMER
        - CANCELLED_BY_SELLER
        - DECLINED
        - ACCEPTED
        - NO_SHOW
      x-enum-elements:
        - name: PENDING
          description: An unaccepted booking. It is visible to both sellers and customers.
        - name: CANCELLED_BY_CUSTOMER
          description: >-
            A customer-cancelled booking. It is visible to both the seller and
            the customer.
        - name: CANCELLED_BY_SELLER
          description: >-
            A seller-cancelled booking. It is visible to both the seller and the
            customer.
        - name: DECLINED
          description: >-
            A declined booking. It had once been pending, but was then declined
            by the seller.
        - name: ACCEPTED
          description: An accepted booking agreed to or accepted by the seller.
        - name: NO_SHOW
          description: >-
            A no-show booking. The booking was accepted at one time, but have
            now been marked as a no-show by

            the seller because the client either missed the booking or cancelled
            it without enough notice.
      description: Supported booking statuses.
      x-release-status: PUBLIC
    Break:
      type: object
      description: A record of an employee's break during a shift.
      x-release-status: PUBLIC
      required:
        - start_at
        - break_type_id
        - name
        - expected_duration
        - is_paid
      properties:
        id:
          type: string
          description: The UUID for this object.
        start_at:
          type: string
          description: >-
            RFC 3339; follows the same timezone information as `Shift`.
            Precision up to

            the minute is respected; seconds are truncated.
          minLength: 1
        end_at:
          type: string
          description: >-
            RFC 3339; follows the same timezone information as `Shift`.
            Precision up to

            the minute is respected; seconds are truncated.
          nullable: true
        break_type_id:
          type: string
          description: The `BreakType` that this `Break` was templated on.
          minLength: 1
        name:
          type: string
          description: A human-readable name.
          minLength: 1
        expected_duration:
          type: string
          description: |-
            Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of
            the break.
          minLength: 1
        is_paid:
          type: boolean
          description: |-
            Whether this break counts towards time worked for compensation
            purposes.
    BreakType:
      type: object
      description: |-
        A defined break template that sets an expectation for possible `Break`
        instances on a `Shift`.
      x-release-status: PUBLIC
      required:
        - location_id
        - break_name
        - expected_duration
        - is_paid
      properties:
        id:
          type: string
          description: The UUID for this object.
          maxLength: 255
        location_id:
          type: string
          description: The ID of the business location this type of break applies to.
          minLength: 1
        break_name:
          type: string
          description: >-
            A human-readable name for this type of break. The name is displayed
            to

            employees in Square products.
          minLength: 1
        expected_duration:
          type: string
          description: |-
            Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of
            this break. Precision less than minutes is truncated.

            Example for break expected duration of 15 minutes: T15M
          minLength: 1
        is_paid:
          type: boolean
          description: |-
            Whether this break counts towards time worked for compensation
            purposes.
        version:
          type: integer
          description: >-
            Used for resolving concurrency issues. The request fails if the
            version

            provided does not match the server version at the time of the
            request. If a value is not

            provided, Square's servers execute a "blind" write; potentially

            overwriting another writer's data.
        created_at:
          type: string
          description: A read-only timestamp in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: A read-only timestamp in RFC 3339 format.
          readOnly: true
    BulkCreateCustomerData:
      type: object
      description: >-
        Defines the customer data provided in individual create requests for a

        [BulkCreateCustomers](api-endpoint:Customers-BulkCreateCustomers)
        operation.
      x-release-status: PUBLIC
      properties:
        given_name:
          type: string
          description: >-
            The given name (that is, the first name) associated with the
            customer profile.
          maxLength: 300
          nullable: true
        family_name:
          type: string
          description: >-
            The family name (that is, the last name) associated with the
            customer profile.
          maxLength: 300
          nullable: true
        company_name:
          type: string
          description: A business name associated with the customer profile.
          maxLength: 500
          nullable: true
        nickname:
          type: string
          description: A nickname for the customer profile.
          maxLength: 100
          nullable: true
        email_address:
          type: string
          description: The email address associated with the customer profile.
          maxLength: 254
          nullable: true
        address:
          $ref: '#/components/schemas/Address'
          description: >-
            The physical address associated with the customer profile. For
            maximum length constraints,

            see [Customer
            addresses](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#address).

            The `first_name` and `last_name` fields are ignored if they are
            present in the request.
          nullable: true
        phone_number:
          type: string
          description: >-
            The phone number associated with the customer profile. The phone
            number must be valid

            and can contain 916 digits, with an optional `+` prefix and country
            code. For more information,

            see [Customer phone
            numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number).
          nullable: true
        reference_id:
          type: string
          description: |-
            An optional second ID used to associate the customer profile with an
            entity in another system.
          maxLength: 100
          nullable: true
        note:
          type: string
          description: A custom note associated with the customer profile.
          nullable: true
        birthday:
          type: string
          description: >-
            The birthday associated with the customer profile, in `YYYY-MM-DD`
            or `MM-DD` format.

            For example, specify `1998-09-21` for September 21, 1998, or `09-21`
            for September 21.

            Birthdays are returned in `YYYY-MM-DD` format, where `YYYY` is the
            specified birth year or

            `0000` if a birth year is not specified.
          nullable: true
        tax_ids:
          $ref: '#/components/schemas/CustomerTaxIds'
          description: >-
            The tax ID associated with the customer profile. This field is
            available only for

            customers of sellers in EU countries or the United Kingdom. For more
            information, see

            [Customer tax
            IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids).
          nullable: true
    BulkCreateCustomersRequest:
      type: object
      description: >-
        Defines the body parameters that can be included in requests to the

        [BulkCreateCustomers](api-endpoint:Customers-BulkCreateCustomers)
        endpoint.
      x-release-status: PUBLIC
      required:
        - customers
      properties:
        customers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BulkCreateCustomerData'
          description: >-
            A map of 1 to 100 individual create requests, represented by
            `idempotency key: { customer data }`

            key-value pairs.


            Each key is an [idempotency
            key](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)

            that uniquely identifies the create request. Each value contains the
            customer data used to create the

            customer profile.
      example:
        customers:
          8bb76c4f-e35d-4c5b-90de-1194cd9179f0:
            address:
              address_line_1: 500 Electric Ave
              address_line_2: Suite 600
              administrative_district_level_1: NY
              country: US
              locality: New York
              postal_code: '10003'
            email_address: Amelia.Earhart@example.com
            family_name: Earhart
            given_name: Amelia
            note: a customer
            phone_number: +1-212-555-4240
            reference_id: YOUR_REFERENCE_ID
          d1689f23-b25d-4932-b2f0-aed00f5e2029:
            address:
              address_line_1: 500 Electric Ave
              address_line_2: Suite 601
              administrative_district_level_1: NY
              country: US
              locality: New York
              postal_code: '10003'
            email_address: Marie.Curie@example.com
            family_name: Curie
            given_name: Marie
            note: another customer
            phone_number: +1-212-444-4240
            reference_id: YOUR_REFERENCE_ID
    BulkCreateCustomersResponse:
      type: object
      description: >-
        Defines the fields included in the response body from the

        [BulkCreateCustomers](api-endpoint:Customers-BulkCreateCustomers)
        endpoint.
      x-release-status: PUBLIC
      properties:
        responses:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CreateCustomerResponse'
          description: >-
            A map of responses that correspond to individual create requests,
            represented by

            key-value pairs.


            Each key is the idempotency key that was provided for a create
            request and each value

            is the corresponding response.

            If the request succeeds, the value is the new customer profile.

            If the request fails, the value contains any errors that occurred
            during the request.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any top-level errors that prevented the bulk operation from running.
      example:
        responses:
          8bb76c4f-e35d-4c5b-90de-1194cd9179f4:
            customer:
              address:
                address_line_1: 500 Electric Ave
                address_line_2: Suite 600
                administrative_district_level_1: NY
                country: US
                locality: New York
                postal_code: '10003'
              created_at: '2024-03-23T20:21:54.859Z'
              creation_source: THIRD_PARTY
              email_address: Amelia.Earhart@example.com
              family_name: Earhart
              given_name: Amelia
              id: 8DDA5NZVBZFGAX0V3HPF81HHE0
              note: a customer
              phone_number: +1-212-555-4240
              preferences:
                email_unsubscribed: false
              reference_id: YOUR_REFERENCE_ID
              updated_at: '2024-03-23T20:21:54.859Z'
              version: 0
          d1689f23-b25d-4932-b2f0-aed00f5e2029:
            customer:
              address:
                address_line_1: 500 Electric Ave
                address_line_2: Suite 601
                administrative_district_level_1: NY
                country: US
                locality: New York
                postal_code: '10003'
              created_at: '2024-03-23T20:21:54.859Z'
              creation_source: THIRD_PARTY
              email_address: Marie.Curie@example.com
              family_name: Curie
              given_name: Marie
              id: N18CPRVXR5214XPBBA6BZQWF3C
              note: another customer
              phone_number: +1-212-444-4240
              preferences:
                email_unsubscribed: false
              reference_id: YOUR_REFERENCE_ID
              updated_at: '2024-03-23T20:21:54.859Z'
              version: 0
    BulkCreateTeamMembersRequest:
      type: object
      description: Represents a bulk create request for `TeamMember` objects.
      x-release-status: PUBLIC
      required:
        - team_members
      properties:
        team_members:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CreateTeamMemberRequest'
          description: >-
            The data used to create the `TeamMember` objects. Each key is the
            `idempotency_key` that maps to the `CreateTeamMemberRequest`.

            The maximum number of create objects is 25.


            If you include a team member's `wage_setting`, you must provide
            `job_id` for each job assignment. To get job IDs,

            call [ListJobs](api-endpoint:Team-ListJobs).
      example:
        team_members:
          idempotency-key-1:
            team_member:
              assigned_locations:
                assignment_type: EXPLICIT_LOCATIONS
                location_ids:
                  - YSGH2WBKG94QZ
                  - GA2Y9HSJ8KRYT
              email_address: joe_doe@gmail.com
              family_name: Doe
              given_name: Joe
              phone_number: '+14159283333'
              reference_id: reference_id_1
          idempotency-key-2:
            team_member:
              assigned_locations:
                assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
              email_address: jane_smith@gmail.com
              family_name: Smith
              given_name: Jane
              phone_number: '+14159223334'
              reference_id: reference_id_2
    BulkCreateTeamMembersResponse:
      type: object
      description: >-
        Represents a response from a bulk create request containing the created
        `TeamMember` objects or error messages.
      x-release-status: PUBLIC
      properties:
        team_members:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CreateTeamMemberResponse'
          description: >-
            The successfully created `TeamMember` objects. Each key is the
            `idempotency_key` that maps to the `CreateTeamMemberRequest`.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: The errors that occurred during the request.
      example:
        team_members:
          idempotency-key-1:
            team_member:
              assigned_locations:
                assignment_type: EXPLICIT_LOCATIONS
                location_ids:
                  - GA2Y9HSJ8KRYT
                  - YSGH2WBKG94QZ
              email_address: joe_doe@gmail.com
              family_name: Doe
              given_name: Joe
              id: ywhG1qfIOoqsHfVRubFV
              is_owner: false
              phone_number: '+14159283333'
              reference_id: reference_id_1
              status: ACTIVE
          idempotency-key-2:
            team_member:
              assigned_locations:
                assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
              email_address: jane_smith@gmail.com
              family_name: Smith
              given_name: Jane
              id: IF_Ncrg7fHhCqxVI9T6R
              is_owner: false
              phone_number: '+14159223334'
              reference_id: reference_id_2
              status: ACTIVE
    BulkCreateVendorsRequest:
      type: object
      description: >-
        Represents an input to a call to
        [BulkCreateVendors](api-endpoint:Vendors-BulkCreateVendors).
      x-release-status: BETA
      required:
        - vendors
      properties:
        vendors:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/Vendor'
          description: >-
            Specifies a set of new [Vendor](entity:Vendor) objects as
            represented by a collection of idempotency-key/`Vendor`-object
            pairs.
      example:
        47bb76a8-c9fb-4f33-9df8-25ce02ca4505:
          contacts:
            - email_address: annie@annieshotsauce.com
              name: Annie Thomas
              phone_number: 1-212-555-4250
          name: Annies Hot Sauce
        vendors:
          8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe:
            account_number: '4025391'
            address:
              address_line_1: 505 Electric Ave
              address_line_2: Suite 600
              administrative_district_level_1: NY
              country: US
              locality: New York
              postal_code: '10003'
            contacts:
              - email_address: joe@joesfreshseafood.com
                name: Joe Burrow
                phone_number: 1-212-555-4250
            name: Joe's Fresh Seafood
            note: a vendor
    BulkCreateVendorsResponse:
      type: object
      description: >-
        Represents an output from a call to
        [BulkCreateVendors](api-endpoint:Vendors-BulkCreateVendors).
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        responses:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CreateVendorResponse'
          description: >-
            A set of [CreateVendorResponse](entity:CreateVendorResponse) objects
            encapsulating successfully created [Vendor](entity:Vendor)

            objects or error responses for failed attempts. The set is
            represented by 

            a collection of idempotency-key/`Vendor`-object or
            idempotency-key/error-object pairs. The idempotency keys correspond
            to those specified

            in the input.
      example:
        47bb76a8-c9fb-4f33-9df8-25ce02ca4505:
          vendor:
            contacts:
              - email_address: annie@annieshotsauce.com
                id: INV_VC_ABYYHBWT1TPL8MFH52PBMENPJ4
                name: Annie Thomas
                phone_number: 1-212-555-4250
            created_at: '2022-03-16T10:21:54.859Z'
            id: INV_V_FMCYHBWT1TPL8MFH52PBMEN92A
            name: Annies Hot Sauce
            status: ACTIVE
            updated_at: '2022-03-16T10:21:54.859Z'
            version: 1
        responses:
          8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe:
            vendor:
              account_number: '4025391'
              address:
                address_line_1: 505 Electric Ave
                address_line_2: Suite 600
                administrative_district_level_1: NY
                country: US
                locality: New York
                postal_code: '10003'
              contacts:
                - email_address: joe@joesfreshseafood.com
                  id: INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A
                  name: Joe Burrow
                  phone_number: 1-212-555-4250
              created_at: '2022-03-16T10:21:54.859Z'
              id: INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4
              name: Joe's Fresh Seafood
              note: a vendor
              status: ACTIVE
              updated_at: '2022-03-16T10:21:54.859Z'
              version: 0
    BulkDeleteBookingCustomAttributesRequest:
      type: object
      description: >-
        Represents a
        [BulkDeleteBookingCustomAttributes](api-endpoint:BookingCustomAttributes-BulkDeleteBookingCustomAttributes)
        request.
      x-release-status: PUBLIC
      required:
        - values
      properties:
        values:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BookingCustomAttributeDeleteRequest'
          description: >-
            A map containing 1 to 25 individual Delete requests. For each
            request, provide an

            arbitrary ID that is unique for this
            `BulkDeleteBookingCustomAttributes` request and the

            information needed to delete a custom attribute.
    BulkDeleteBookingCustomAttributesResponse:
      type: object
      description: >-
        Represents a
        [BulkDeleteBookingCustomAttributes](api-endpoint:BookingCustomAttributes-BulkDeleteBookingCustomAttributes)
        response,

        which contains a map of responses that each corresponds to an individual
        delete request.
      x-release-status: PUBLIC
      properties:
        values:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BookingCustomAttributeDeleteResponse'
          description: >-
            A map of responses that correspond to individual delete requests.
            Each response has the

            same ID as the corresponding request and contains `booking_id` and 
            `errors` field.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        errors: []
        values:
          id1:
            booking_id: N3NCVYY3WS27HF0HKANA3R9FP8
            errors: []
          id2:
            booking_id: SY8EMWRNDN3TQDP2H4KS1QWMMM
            errors: []
          id3:
            booking_id: SY8EMWRNDN3TQDP2H4KS1QWMMM
            errors: []
    BulkDeleteCustomersRequest:
      type: object
      description: >-
        Defines the body parameters that can be included in requests to the

        [BulkDeleteCustomers](api-endpoint:Customers-BulkDeleteCustomers)
        endpoint.
      x-release-status: PUBLIC
      required:
        - customer_ids
      properties:
        customer_ids:
          type: array
          items:
            type: string
          description: The IDs of the [customer profiles](entity:Customer) to delete.
      example:
        customer_ids:
          - 8DDA5NZVBZFGAX0V3HPF81HHE0
          - N18CPRVXR5214XPBBA6BZQWF3C
          - 2GYD7WNXF7BJZW1PMGNXZ3Y8M8
    BulkDeleteCustomersResponse:
      type: object
      description: >-
        Defines the fields included in the response body from the

        [BulkDeleteCustomers](api-endpoint:Customers-BulkDeleteCustomers)
        endpoint.
      x-release-status: PUBLIC
      properties:
        responses:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DeleteCustomerResponse'
          description: >-
            A map of responses that correspond to individual delete requests,
            represented by

            key-value pairs.


            Each key is the customer ID that was specified for a delete request
            and each value

            is the corresponding response.

            If the request succeeds, the value is an empty object (`{ }`).

            If the request fails, the value contains any errors that occurred
            during the request.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any top-level errors that prevented the bulk operation from running.
      example:
        responses:
          2GYD7WNXF7BJZW1PMGNXZ3Y8M8:
            errors:
              - category: INVALID_REQUEST_ERROR
                code: NOT_FOUND
                detail: Customer with ID `2GYD7WNXF7BJZW1PMGNXZ3Y8M8` not found.
          8DDA5NZVBZFGAX0V3HPF81HHE0: {}
          N18CPRVXR5214XPBBA6BZQWF3C: {}
    BulkDeleteLocationCustomAttributesRequest:
      type: object
      description: >-
        Represents a
        [BulkDeleteLocationCustomAttributes](api-endpoint:LocationCustomAttributes-BulkDeleteLocationCustomAttributes)
        request.
      x-release-status: BETA
      required:
        - values
      properties:
        values:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/BulkDeleteLocationCustomAttributesRequestLocationCustomAttributeDeleteRequest
          description: >-
            The data used to update the `CustomAttribute` objects.

            The keys must be unique and are used to map to the corresponding
            response.
      example:
        values:
          id1:
            key: bestseller
            location_id: L0TBCBTB7P8RQ
          id2:
            key: bestseller
            location_id: L9XMD04V3STJX
          id3:
            key: phone-number
            location_id: L0TBCBTB7P8RQ
    BulkDeleteLocationCustomAttributesRequestLocationCustomAttributeDeleteRequest:
      type: object
      description: >-
        Represents an individual delete request in a
        [BulkDeleteLocationCustomAttributes](api-endpoint:LocationCustomAttributes-BulkDeleteLocationCustomAttributes)

        request. An individual request contains an optional ID of the associated
        custom attribute definition

        and optional key of the associated custom attribute definition.
      x-release-status: BETA
      properties:
        key:
          type: string
          description: >-
            The key of the associated custom attribute definition.

            Represented as a qualified key if the requesting app is not the
            definition owner.
          pattern: ^([a-zA-Z0-9_-]+:)?[a-zA-Z0-9_-]{1,60}$
          readOnly: true
    BulkDeleteLocationCustomAttributesResponse:
      type: object
      description: >-
        Represents a
        [BulkDeleteLocationCustomAttributes](api-endpoint:LocationCustomAttributes-BulkDeleteLocationCustomAttributes)
        response,

        which contains a map of responses that each corresponds to an individual
        delete request.
      x-release-status: BETA
      required:
        - values
      properties:
        values:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/BulkDeleteLocationCustomAttributesResponseLocationCustomAttributeDeleteResponse
          description: >-
            A map of responses that correspond to individual delete requests.
            Each response has the

            same key as the corresponding request.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        values:
          id1:
            errors: []
            location_id: L0TBCBTB7P8RQ
          id2:
            errors: []
            location_id: L9XMD04V3STJX
          id3:
            errors: []
            location_id: L0TBCBTB7P8RQ
    BulkDeleteLocationCustomAttributesResponseLocationCustomAttributeDeleteResponse:
      type: object
      description: >-
        Represents an individual delete response in a
        [BulkDeleteLocationCustomAttributes](api-endpoint:LocationCustomAttributes-BulkDeleteLocationCustomAttributes)

        request.
      x-release-status: BETA
      properties:
        location_id:
          type: string
          description: The ID of the location associated with the custom attribute.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            Errors that occurred while processing the individual
            LocationCustomAttributeDeleteRequest request
      example:
        errors: []
        location_id: L0TBCBTB7P8RQ
    BulkDeleteMerchantCustomAttributesRequest:
      type: object
      description: >-
        Represents a
        [BulkDeleteMerchantCustomAttributes](api-endpoint:MerchantCustomAttributes-BulkDeleteMerchantCustomAttributes)
        request.
      x-release-status: BETA
      required:
        - values
      properties:
        values:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/BulkDeleteMerchantCustomAttributesRequestMerchantCustomAttributeDeleteRequest
          description: >-
            The data used to update the `CustomAttribute` objects.

            The keys must be unique and are used to map to the corresponding
            response.
      example:
        values:
          id1:
            key: alternative_seller_name
            merchant_id: DM7VKY8Q63GNP
          id2:
            key: has_seen_tutorial
            merchant_id: DM7VKY8Q63GNP
    BulkDeleteMerchantCustomAttributesRequestMerchantCustomAttributeDeleteRequest:
      type: object
      description: >-
        Represents an individual delete request in a
        [BulkDeleteMerchantCustomAttributes](api-endpoint:MerchantCustomAttributes-BulkDeleteMerchantCustomAttributes)

        request. An individual request contains an optional ID of the associated
        custom attribute definition

        and optional key of the associated custom attribute definition.
      x-release-status: BETA
      properties:
        key:
          type: string
          description: >-
            The key of the associated custom attribute definition.

            Represented as a qualified key if the requesting app is not the
            definition owner.
          pattern: ^([a-zA-Z0-9_-]+:)?[a-zA-Z0-9_-]{1,60}$
          readOnly: true
    BulkDeleteMerchantCustomAttributesResponse:
      type: object
      description: >-
        Represents a
        [BulkDeleteMerchantCustomAttributes](api-endpoint:MerchantCustomAttributes-BulkDeleteMerchantCustomAttributes)
        response,

        which contains a map of responses that each corresponds to an individual
        delete request.
      x-release-status: BETA
      required:
        - values
      properties:
        values:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/BulkDeleteMerchantCustomAttributesResponseMerchantCustomAttributeDeleteResponse
          description: >-
            A map of responses that correspond to individual delete requests.
            Each response has the

            same key as the corresponding request.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        values:
          id1:
            errors: []
            merchant_id: DM7VKY8Q63GNP
          id2:
            errors: []
            merchant_id: DM7VKY8Q63GNP
    BulkDeleteMerchantCustomAttributesResponseMerchantCustomAttributeDeleteResponse:
      type: object
      description: >-
        Represents an individual delete response in a
        [BulkDeleteMerchantCustomAttributes](api-endpoint:MerchantCustomAttributes-BulkDeleteMerchantCustomAttributes)

        request.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            Errors that occurred while processing the individual
            MerchantCustomAttributeDeleteRequest request
      example:
        errors: []
        merchant_id: DM7VKY8Q63GNP
    BulkDeleteOrderCustomAttributesRequest:
      type: object
      description: >-
        Represents a bulk delete request for one or more order custom
        attributes.
      x-release-status: BETA
      required:
        - values
      properties:
        values:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/BulkDeleteOrderCustomAttributesRequestDeleteCustomAttribute
          description: >-
            A map of requests that correspond to individual delete operations
            for custom attributes.
      example:
        values:
          cover-count:
            key: cover-count
            order_id: 7BbXGEIWNldxAzrtGf9GPVZTwZ4F
          table-number:
            key: table-number
            order_id: 7BbXGEIWNldxAzrtGf9GPVZTwZ4F
    BulkDeleteOrderCustomAttributesRequestDeleteCustomAttribute:
      type: object
      description: Represents one delete within the bulk operation.
      x-release-status: BETA
      required:
        - order_id
      properties:
        key:
          type: string
          description: >-
            The key of the custom attribute to delete.  This key must match the
            key 

            of an existing custom attribute definition.
          minLength: 1
          pattern: ^([a-zA-Z0-9_-]+:)?[a-zA-Z0-9_-]{1,60}$
          readOnly: true
        order_id:
          type: string
          description: The ID of the target [order](entity:Order).
          minLength: 1
          maxLength: 255
    BulkDeleteOrderCustomAttributesResponse:
      type: object
      description: Represents a response from deleting one or more order custom attributes.
      x-release-status: BETA
      required:
        - values
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        values:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DeleteOrderCustomAttributeResponse'
          description: >2-
             A map of responses that correspond to individual delete requests. Each response has the same ID 
            as the corresponding request and contains either a
            `custom_attribute` or an `errors` field.
      example:
        values:
          cover-count: {}
          table-number: {}
    BulkRetrieveBookingsRequest:
      type: object
      description: Request payload for bulk retrieval of bookings.
      x-release-status: PUBLIC
      required:
        - booking_ids
      properties:
        booking_ids:
          type: array
          items:
            type: string
          description: >-
            A non-empty list of [Booking](entity:Booking) IDs specifying
            bookings to retrieve.
    BulkRetrieveBookingsResponse:
      type: object
      description: Response payload for bulk retrieval of bookings.
      x-release-status: PUBLIC
      properties:
        bookings:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RetrieveBookingResponse'
          description: >-
            Requested bookings returned as a map containing `booking_id` as the
            key and `RetrieveBookingResponse` as the value.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
      example:
        bookings:
          sc3p3m7dvctfr1:
            booking:
              all_day: false
              appointment_segments:
                - any_team_member: false
                  duration_minutes: 60
                  service_variation_id: VG4FYBKK3UL6UITOEYQ6MFLS
                  service_variation_version: 1641341724039
                  team_member_id: TMjiqI3PxyLMKr4k
              created_at: '2023-04-26T18:19:21Z'
              customer_id: 4TDWKN9E8165X8Z77MRS0VFMJM
              id: sc3p3m7dvctfr1
              location_id: LY6WNBPVM6VGV
              start_at: '2023-05-01T14:00:00Z'
              status: ACCEPTED
              updated_at: '2023-04-26T18:19:21Z'
              version: 0
            errors: []
          tdegug1dvctdef:
            errors:
              - category: INVALID_REQUEST_ERROR
                code: NOT_FOUND
                detail: Specified booking was not found.
                field: booking_id
          tdegug1fqni3wh:
            booking:
              all_day: false
              appointment_segments:
                - any_team_member: false
                  duration_minutes: 60
                  service_variation_id: VG4FYBKK3UL6UITOEYQ6MFLS
                  service_variation_version: 1641341724039
                  team_member_id: TMjiqI3PxyLMKr4k
              created_at: '2023-04-26T18:19:30Z'
              customer_id: 4TDWKN9E8165X8Z77MRS0VFMJM
              id: tdegug1fqni3wh
              location_id: LY6WNBPVM6VGV
              start_at: '2023-05-02T14:00:00Z'
              status: ACCEPTED
              updated_at: '2023-04-26T18:19:30Z'
              version: 0
            errors: []
        errors: []
    BulkRetrieveCustomersRequest:
      type: object
      description: >-
        Defines the body parameters that can be included in requests to the

        [BulkRetrieveCustomers](api-endpoint:Customers-BulkRetrieveCustomers)
        endpoint.
      x-release-status: PUBLIC
      required:
        - customer_ids
      properties:
        customer_ids:
          type: array
          items:
            type: string
          description: The IDs of the [customer profiles](entity:Customer) to retrieve.
      example:
        customer_ids:
          - 8DDA5NZVBZFGAX0V3HPF81HHE0
          - N18CPRVXR5214XPBBA6BZQWF3C
          - 2GYD7WNXF7BJZW1PMGNXZ3Y8M8
    BulkRetrieveCustomersResponse:
      type: object
      description: >-
        Defines the fields included in the response body from the

        [BulkRetrieveCustomers](api-endpoint:Customers-BulkRetrieveCustomers)
        endpoint.
      x-release-status: PUBLIC
      properties:
        responses:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RetrieveCustomerResponse'
          description: >-
            A map of responses that correspond to individual retrieve requests,
            represented by

            key-value pairs.


            Each key is the customer ID that was specified for a retrieve
            request and each value

            is the corresponding response.

            If the request succeeds, the value is the requested customer
            profile.

            If the request fails, the value contains any errors that occurred
            during the request.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any top-level errors that prevented the bulk operation from running.
      example:
        responses:
          2GYD7WNXF7BJZW1PMGNXZ3Y8M8:
            errors:
              - category: INVALID_REQUEST_ERROR
                code: NOT_FOUND
                detail: Customer with ID `2GYD7WNXF7BJZW1PMGNXZ3Y8M8` not found.
          8DDA5NZVBZFGAX0V3HPF81HHE0:
            customer:
              birthday: '1897-07-24'
              created_at: '2024-01-19T00:27:54.59Z'
              creation_source: THIRD_PARTY
              email_address: New.Amelia.Earhart@example.com
              family_name: Earhart
              given_name: Amelia
              id: 8DDA5NZVBZFGAX0V3HPF81HHE0
              note: updated customer note
              preferences:
                email_unsubscribed: false
              updated_at: '2024-01-19T00:38:06Z'
              version: 3
          N18CPRVXR5214XPBBA6BZQWF3C:
            customer:
              created_at: '2024-01-19T00:27:54.59Z'
              creation_source: THIRD_PARTY
              family_name: Curie
              given_name: Marie
              id: N18CPRVXR5214XPBBA6BZQWF3C
              preferences:
                email_unsubscribed: false
              updated_at: '2024-01-19T00:38:06Z'
              version: 1
    BulkRetrieveTeamMemberBookingProfilesRequest:
      type: object
      description: >-
        Request payload for the
        [BulkRetrieveTeamMemberBookingProfiles](api-endpoint:Bookings-BulkRetrieveTeamMemberBookingProfiles)
        endpoint.
      x-release-status: PUBLIC
      required:
        - team_member_ids
      properties:
        team_member_ids:
          type: array
          items:
            type: string
          description: >-
            A non-empty list of IDs of team members whose booking profiles you
            want to retrieve.
    BulkRetrieveTeamMemberBookingProfilesResponse:
      type: object
      description: >-
        Response payload for the
        [BulkRetrieveTeamMemberBookingProfiles](api-endpoint:Bookings-BulkRetrieveTeamMemberBookingProfiles)
        endpoint.
      x-release-status: PUBLIC
      properties:
        team_member_booking_profiles:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RetrieveTeamMemberBookingProfileResponse'
          description: >-
            The returned team members' booking profiles, as a map with
            `team_member_id` as the key and
            [TeamMemberBookingProfile](entity:TeamMemberBookingProfile) the
            value.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
      example:
        errors: []
        team_member_booking_profiles:
          TMXUrsBWWcHTt79t:
            errors:
              - category: INVALID_REQUEST_ERROR
                code: NOT_FOUND
                detail: Resource not found.
          TMaJcbiRqPIGZuS9:
            errors: []
            team_member_booking_profile:
              display_name: Sandbox Staff 1
              is_bookable: true
              team_member_id: TMaJcbiRqPIGZuS9
          TMtdegug1fqni3wh:
            errors: []
            team_member_booking_profile:
              display_name: Sandbox Staff 2
              is_bookable: true
              team_member_id: TMtdegug1fqni3wh
    BulkRetrieveVendorsRequest:
      type: object
      description: >-
        Represents an input to a call to
        [BulkRetrieveVendors](api-endpoint:Vendors-BulkRetrieveVendors).
      x-release-status: BETA
      properties:
        vendor_ids:
          type: array
          items:
            type: string
          description: IDs of the [Vendor](entity:Vendor) objects to retrieve.
          nullable: true
      example:
        vendor_ids:
          - INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4
    BulkRetrieveVendorsResponse:
      type: object
      description: >-
        Represents an output from a call to
        [BulkRetrieveVendors](api-endpoint:Vendors-BulkRetrieveVendors).
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        responses:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RetrieveVendorResponse'
          description: >-
            The set of [RetrieveVendorResponse](entity:RetrieveVendorResponse)
            objects encapsulating successfully retrieved [Vendor](entity:Vendor)

            objects or error responses for failed attempts. The set is
            represented by 

            a collection of `Vendor`-ID/`Vendor`-object or
            `Vendor`-ID/error-object pairs.
      example:
        responses:
          INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4:
            vendor:
              account_number: '4025391'
              address:
                address_line_1: 505 Electric Ave
                address_line_2: Suite 600
                administrative_district_level_1: NY
                country: US
                locality: New York
                postal_code: '10003'
              contacts:
                - email_address: joe@joesfreshseafood.com
                  id: INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A
                  name: Joe Burrow
                  phone_number: 1-212-555-4250
              created_at: '2022-03-16T10:21:54.859Z'
              id: INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4
              name: Joe's Fresh Seafood
              note: a vendor
              status: ACTIVE
              updated_at: '2022-03-16T10:21:54.859Z'
              version: 1
    BulkSwapPlanRequest:
      type: object
      description: |-
        Defines input parameters in a call to the
        [BulkSwapPlan](api-endpoint:Subscriptions-BulkSwapPlan) endpoint.
      x-release-status: BETA
      required:
        - new_plan_variation_id
        - old_plan_variation_id
        - location_id
      properties:
        new_plan_variation_id:
          type: string
          description: |-
            The ID of the new subscription plan variation.

            This field is required.
          minLength: 1
        old_plan_variation_id:
          type: string
          description: >-
            The ID of the plan variation whose subscriptions should be swapped.
            Active subscriptions

            using this plan variation will be subscribed to the new plan
            variation on their next billing

            day.
          minLength: 1
        location_id:
          type: string
          description: The ID of the location to associate with the swapped subscriptions.
          minLength: 1
      example:
        location_id: S8GWD5R9QB376
        new_plan_variation_id: FQ7CDXXWSLUJRPM3GFJSJGZ7
        old_plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
    BulkSwapPlanResponse:
      type: object
      description: |-
        Defines output parameters in a response of the
        [BulkSwapPlan](api-endpoint:Subscriptions-BulkSwapPlan) endpoint.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered during the request.
        affected_subscriptions:
          type: integer
          description: The number of affected subscriptions.
      example:
        affected_subscriptions: 12
    BulkUpdateCustomerData:
      type: object
      description: >-
        Defines the customer data provided in individual update requests for a

        [BulkUpdateCustomers](api-endpoint:Customers-BulkUpdateCustomers)
        operation.
      x-release-status: PUBLIC
      properties:
        given_name:
          type: string
          description: >-
            The given name (that is, the first name) associated with the
            customer profile.
          maxLength: 300
          nullable: true
        family_name:
          type: string
          description: >-
            The family name (that is, the last name) associated with the
            customer profile.
          maxLength: 300
          nullable: true
        company_name:
          type: string
          description: A business name associated with the customer profile.
          maxLength: 500
          nullable: true
        nickname:
          type: string
          description: A nickname for the customer profile.
          maxLength: 100
          nullable: true
        email_address:
          type: string
          description: The email address associated with the customer profile.
          maxLength: 254
          nullable: true
        address:
          $ref: '#/components/schemas/Address'
          description: >-
            The physical address associated with the customer profile. For
            maximum length constraints,

            see [Customer
            addresses](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#address).

            The `first_name` and `last_name` fields are ignored if they are
            present in the request.
          nullable: true
        phone_number:
          type: string
          description: >-
            The phone number associated with the customer profile. The phone
            number must be valid

            and can contain 916 digits, with an optional `+` prefix and country
            code. For more information,

            see [Customer phone
            numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number).
          nullable: true
        reference_id:
          type: string
          description: |-
            An optional second ID used to associate the customer profile with an
            entity in another system.
          maxLength: 100
          nullable: true
        note:
          type: string
          description: An custom note associates with the customer profile.
          nullable: true
        birthday:
          type: string
          description: >-
            The birthday associated with the customer profile, in `YYYY-MM-DD`
            or `MM-DD` format.

            For example, specify `1998-09-21` for September 21, 1998, or `09-21`
            for September 21.

            Birthdays are returned in `YYYY-MM-DD` format, where `YYYY` is the
            specified birth year or

            `0000` if a birth year is not specified.
          nullable: true
        tax_ids:
          $ref: '#/components/schemas/CustomerTaxIds'
          description: >-
            The tax ID associated with the customer profile. This field is
            available only for

            customers of sellers in EU countries or the United Kingdom. For more
            information, see

            [Customer tax
            IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids).
          nullable: true
        version:
          type: integer
          description: >-
            The current version of the customer profile.


            As a best practice, you should include this field to enable

            [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control.
          format: int64
    BulkUpdateCustomersRequest:
      type: object
      description: >-
        Defines the body parameters that can be included in requests to the

        [BulkUpdateCustomers](api-endpoint:Customers-BulkUpdateCustomers)
        endpoint.
      x-release-status: PUBLIC
      required:
        - customers
      properties:
        customers:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BulkUpdateCustomerData'
          description: >-
            A map of 1 to 100 individual update requests, represented by
            `customer ID: { customer data }`

            key-value pairs.


            Each key is the ID of the [customer profile](entity:Customer) to
            update. To update a customer profile

            that was created by merging existing profiles, provide the ID of the
            newly created profile.


            Each value contains the updated customer data. Only new or changed
            fields are required. To add or

            update a field, specify the new value. To remove a field, specify
            `null`.
      example:
        customers:
          8DDA5NZVBZFGAX0V3HPF81HHE0:
            email_address: New.Amelia.Earhart@example.com
            note: updated customer note
            phone_number: null
            version: 2
          N18CPRVXR5214XPBBA6BZQWF3C:
            family_name: Curie
            given_name: Marie
            version: 0
    BulkUpdateCustomersResponse:
      type: object
      description: >-
        Defines the fields included in the response body from the

        [BulkUpdateCustomers](api-endpoint:Customers-BulkUpdateCustomers)
        endpoint.
      x-release-status: PUBLIC
      properties:
        responses:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UpdateCustomerResponse'
          description: >-
            A map of responses that correspond to individual update requests,
            represented by

            key-value pairs.


            Each key is the customer ID that was specified for an update request
            and each value

            is the corresponding response.

            If the request succeeds, the value is the updated customer profile.

            If the request fails, the value contains any errors that occurred
            during the request.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any top-level errors that prevented the bulk operation from running.
      example:
        responses:
          8DDA5NZVBZFGAX0V3HPF81HHE0:
            customer:
              birthday: '1897-07-24'
              created_at: '2024-01-19T00:27:54.59Z'
              creation_source: THIRD_PARTY
              email_address: New.Amelia.Earhart@example.com
              family_name: Earhart
              given_name: Amelia
              id: 8DDA5NZVBZFGAX0V3HPF81HHE0
              note: updated customer note
              preferences:
                email_unsubscribed: false
              updated_at: '2024-01-19T00:38:06Z'
              version: 3
          N18CPRVXR5214XPBBA6BZQWF3C:
            customer:
              created_at: '2024-01-19T00:27:54.59Z'
              creation_source: THIRD_PARTY
              family_name: Curie
              given_name: Marie
              id: N18CPRVXR5214XPBBA6BZQWF3C
              preferences:
                email_unsubscribed: false
              updated_at: '2024-01-19T00:38:06Z'
              version: 1
    BulkUpdateTeamMembersRequest:
      type: object
      description: Represents a bulk update request for `TeamMember` objects.
      x-release-status: PUBLIC
      required:
        - team_members
      properties:
        team_members:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UpdateTeamMemberRequest'
          description: >-
            The data used to update the `TeamMember` objects. Each key is the
            `team_member_id` that maps to the `UpdateTeamMemberRequest`.

            The maximum number of update objects is 25.


            For each team member, include the fields to add, change, or clear.
            Fields can be cleared using a null value.

            To update `wage_setting.job_assignments`, you must provide the
            complete list of job assignments. If needed,

            call [ListJobs](api-endpoint:Team-ListJobs) to get the required
            `job_id` values.
      example:
        team_members:
          AFMwA08kR-MIF-3Vs0OE:
            team_member:
              assigned_locations:
                assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
              email_address: jane_smith@gmail.com
              family_name: Smith
              given_name: Jane
              is_owner: false
              phone_number: '+14159223334'
              reference_id: reference_id_2
              status: ACTIVE
          fpgteZNMaf0qOK-a4t6P:
            team_member:
              assigned_locations:
                assignment_type: EXPLICIT_LOCATIONS
                location_ids:
                  - YSGH2WBKG94QZ
                  - GA2Y9HSJ8KRYT
              email_address: joe_doe@gmail.com
              family_name: Doe
              given_name: Joe
              is_owner: false
              phone_number: '+14159283333'
              reference_id: reference_id_1
              status: ACTIVE
    BulkUpdateTeamMembersResponse:
      type: object
      description: >-
        Represents a response from a bulk update request containing the updated
        `TeamMember` objects or error messages.
      x-release-status: PUBLIC
      properties:
        team_members:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UpdateTeamMemberResponse'
          description: >-
            The successfully updated `TeamMember` objects. Each key is the
            `team_member_id` that maps to the `UpdateTeamMemberRequest`.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: The errors that occurred during the request.
      example:
        team_members:
          AFMwA08kR-MIF-3Vs0OE:
            team_member:
              assigned_locations:
                assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
              created_at: '2020-03-24T18:14:00Z'
              email_address: jane_smith@example.com
              family_name: Smith
              given_name: Jane
              id: AFMwA08kR-MIF-3Vs0OE
              is_owner: false
              phone_number: '+14159223334'
              reference_id: reference_id_2
              status: ACTIVE
              updated_at: '2020-03-24T18:18:00Z'
          fpgteZNMaf0qOK-a4t6P:
            team_member:
              assigned_locations:
                assignment_type: EXPLICIT_LOCATIONS
                location_ids:
                  - GA2Y9HSJ8KRYT
                  - YSGH2WBKG94QZ
              created_at: '2020-03-24T18:14:00Z'
              email_address: joe_doe@example.com
              family_name: Doe
              given_name: Joe
              id: fpgteZNMaf0qOK-a4t6P
              is_owner: false
              phone_number: '+14159283333'
              reference_id: reference_id_1
              status: ACTIVE
              updated_at: '2020-03-24T18:18:00Z'
    BulkUpdateVendorsRequest:
      type: object
      description: >-
        Represents an input to a call to
        [BulkUpdateVendors](api-endpoint:Vendors-BulkUpdateVendors).
      x-release-status: BETA
      required:
        - vendors
      properties:
        vendors:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UpdateVendorRequest'
          description: >-
            A set of [UpdateVendorRequest](entity:UpdateVendorRequest) objects
            encapsulating to-be-updated [Vendor](entity:Vendor)

            objects. The set is represented by  a collection of
            `Vendor`-ID/`UpdateVendorRequest`-object pairs.
      example:
        vendors:
          FMCYHBWT1TPL8MFH52PBMEN92A:
            address:
              address_line_1: 202 Mill St
              administrative_district_level_1: NJ
              country: US
              locality: Moorestown
              postal_code: '08057'
            status: ACTIVE
            version: 10
          INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4:
            note: favorite vendor
            status: ACTIVE
            version: 30
    BulkUpdateVendorsResponse:
      type: object
      description: >-
        Represents an output from a call to
        [BulkUpdateVendors](api-endpoint:Vendors-BulkUpdateVendors).
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered when the request fails.
        responses:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UpdateVendorResponse'
          description: >-
            A set of [UpdateVendorResponse](entity:UpdateVendorResponse) objects
            encapsulating successfully created [Vendor](entity:Vendor)

            objects or error responses for failed attempts. The set is
            represented by a collection of
            `Vendor`-ID/`UpdateVendorResponse`-object or 

            `Vendor`-ID/error-object pairs.
      example:
        responses:
          INV_V_FMCYHBWT1TPL8MFH52PBMEN92A:
            vendor:
              address:
                address_line_1: 202 Mill St
                administrative_district_level_1: NJ
                country: US
                locality: Moorestown
                postal_code: '08057'
              contacts:
                - email_address: annie@annieshotsauce.com
                  id: INV_VC_ABYYHBWT1TPL8MFH52PBMENPJ4
                  name: Annie Thomas
                  ordinal: 0
                  phone_number: 1-212-555-4250
              created_at: '2022-03-16T10:21:54.859Z'
              id: INV_V_FMCYHBWT1TPL8MFH52PBMEN92A
              name: Annies Hot Sauce
              status: ACTIVE
              updated_at: '2022-03-16T20:21:54.859Z'
              version: 11
          INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4:
            vendor:
              account_number: '4025391'
              address:
                address_line_1: 505 Electric Ave
                address_line_2: Suite 600
                administrative_district_level_1: NY
                country: US
                locality: New York
                postal_code: '10003'
              contacts:
                - email_address: joe@joesfreshseafood.com
                  id: INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A
                  name: Joe Burrow
                  ordinal: 0
                  phone_number: 1-212-555-4250
              created_at: '2022-03-16T10:10:54.859Z'
              id: INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4
              name: Joe's Fresh Seafood
              note: favorite vendor
              status: ACTIVE
              updated_at: '2022-03-16T20:21:54.859Z'
              version: 31
    BulkUpsertBookingCustomAttributesRequest:
      type: object
      description: >-
        Represents a
        [BulkUpsertBookingCustomAttributes](api-endpoint:BookingCustomAttributes-BulkUpsertBookingCustomAttributes)
        request.
      x-release-status: PUBLIC
      required:
        - values
      properties:
        values:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BookingCustomAttributeUpsertRequest'
          description: >-
            A map containing 1 to 25 individual upsert requests. For each
            request, provide an

            arbitrary ID that is unique for this
            `BulkUpsertBookingCustomAttributes` request and the

            information needed to create or update a custom attribute.
    BulkUpsertBookingCustomAttributesResponse:
      type: object
      description: >-
        Represents a
        [BulkUpsertBookingCustomAttributes](api-endpoint:BookingCustomAttributes-BulkUpsertBookingCustomAttributes)
        response,

        which contains a map of responses that each corresponds to an individual
        upsert request.
      x-release-status: PUBLIC
      properties:
        values:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BookingCustomAttributeUpsertResponse'
          description: >-
            A map of responses that correspond to individual upsert requests.
            Each response has the

            same ID as the corresponding request and contains either a
            `booking_id` and `custom_attribute` or an `errors` field.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        errors: []
        values:
          id1:
            booking_id: N3NCVYY3WS27HF0HKANA3R9FP8
            custom_attribute:
              created_at: '2022-11-16T23:14:47Z'
              key: favoriteShampoo
              updated_at: '2022-11-16T00:16:23Z'
              value: Spring Fresh
              version: 1
              visibility: VISIBILITY_READ_WRITE_VALUES
            errors: []
          id2:
            booking_id: SY8EMWRNDN3TQDP2H4KS1QWMMM
            custom_attribute:
              created_at: '2022-11-16T00:16:20Z'
              key: hasShoes
              updated_at: '2022-11-16T00:16:23Z'
              value: false
              version: 2
              visibility: VISIBILITY_READ_WRITE_VALUES
            errors: []
          id3:
            booking_id: SY8EMWRNDN3TQDP2H4KS1QWMMM
            custom_attribute:
              created_at: '2022-11-16T00:16:20Z'
              key: favoriteShampoo
              updated_at: '2022-11-16T00:16:23Z'
              value: Hydro-Cool
              version: 2
              visibility: VISIBILITY_READ_WRITE_VALUES
            errors: []
          id4:
            booking_id: N3NCVYY3WS27HF0HKANA3R9FP8
            custom_attribute:
              created_at: '2022-11-16T23:14:47Z'
              key: partySize
              updated_at: '2022-11-16T00:16:23Z'
              value: 4
              version: 1
              visibility: VISIBILITY_READ_WRITE_VALUES
            errors: []
          id5:
            booking_id: 70548QG1HN43B05G0KCZ4MMC1G
            custom_attribute:
              created_at: '2022-11-16T00:16:20Z'
              key: celebrating
              updated_at: '2022-11-16T00:16:23Z'
              value: birthday
              version: 2
              visibility: VISIBILITY_READ_WRITE_VALUES
            errors: []
    BulkUpsertCustomerCustomAttributesRequest:
      type: object
      description: >-
        Represents a
        [BulkUpsertCustomerCustomAttributes](api-endpoint:CustomerCustomAttributes-BulkUpsertCustomerCustomAttributes)
        request.
      x-release-status: PUBLIC
      required:
        - values
      properties:
        values:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/BulkUpsertCustomerCustomAttributesRequestCustomerCustomAttributeUpsertRequest
          description: >-
            A map containing 1 to 25 individual upsert requests. For each
            request, provide an

            arbitrary ID that is unique for this
            `BulkUpsertCustomerCustomAttributes` request and the

            information needed to create or update a custom attribute.
      example:
        values:
          id1:
            custom_attribute:
              key: favoritemovie
              value: Dune
            customer_id: N3NCVYY3WS27HF0HKANA3R9FP8
          id2:
            custom_attribute:
              key: ownsmovie
              value: false
            customer_id: SY8EMWRNDN3TQDP2H4KS1QWMMM
          id3:
            custom_attribute:
              key: favoritemovie
              value: Star Wars
            customer_id: SY8EMWRNDN3TQDP2H4KS1QWMMM
          id4:
            custom_attribute:
              key: square:a0f1505a-2aa1-490d-91a8-8d31ff181808
              value: '10.5'
            customer_id: N3NCVYY3WS27HF0HKANA3R9FP8
          id5:
            custom_attribute:
              key: sq0ids-0evKIskIGaY45fCyNL66aw:backupemail
              value: fake-email@squareup.com
            customer_id: 70548QG1HN43B05G0KCZ4MMC1G
    BulkUpsertCustomerCustomAttributesRequestCustomerCustomAttributeUpsertRequest:
      type: object
      description: >-
        Represents an individual upsert request in a
        [BulkUpsertCustomerCustomAttributes](api-endpoint:CustomerCustomAttributes-BulkUpsertCustomerCustomAttributes)

        request. An individual request contains a customer ID, the custom
        attribute to create or update,

        and an optional idempotency key.
      x-release-status: PUBLIC
      required:
        - customer_id
        - custom_attribute
      properties:
        customer_id:
          type: string
          description: The ID of the target [customer profile](entity:Customer).
          minLength: 1
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The custom attribute to create or update, with following fields:


            - `key`. This key must match the `key` of a custom attribute
            definition in the Square seller 

            account. If the requesting application is not the definition owner,
            you must provide the qualified key.


            - `value`. This value must conform to the `schema` specified by the
            definition. 

            For more information, see [Value data
            types](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attributes#value-data-types).


            - `version`. To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control for update operations, include this optional field in the
            request and set the

            value to the current version of the custom attribute.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this individual upsert request, used to
            ensure idempotency.

            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
          nullable: true
    BulkUpsertCustomerCustomAttributesResponse:
      type: object
      description: >-
        Represents a
        [BulkUpsertCustomerCustomAttributes](api-endpoint:CustomerCustomAttributes-BulkUpsertCustomerCustomAttributes)
        response,

        which contains a map of responses that each corresponds to an individual
        upsert request.
      x-release-status: PUBLIC
      properties:
        values:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/BulkUpsertCustomerCustomAttributesResponseCustomerCustomAttributeUpsertResponse
          description: >-
            A map of responses that correspond to individual upsert requests.
            Each response has the

            same ID as the corresponding request and contains either a
            `customer_id` and `custom_attribute` or an `errors` field.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        values:
          id1:
            custom_attribute:
              created_at: '2021-12-08T23:14:47Z'
              key: favoritemovie
              updated_at: '2021-12-09T00:16:23Z'
              value: Dune
              version: 1
              visibility: VISIBILITY_READ_WRITE_VALUES
            customer_id: N3NCVYY3WS27HF0HKANA3R9FP8
          id2:
            custom_attribute:
              created_at: '2021-12-09T00:16:20Z'
              key: ownsmovie
              updated_at: '2021-12-09T00:16:23Z'
              value: false
              version: 2
              visibility: VISIBILITY_READ_WRITE_VALUES
            customer_id: SY8EMWRNDN3TQDP2H4KS1QWMMM
          id3:
            custom_attribute:
              created_at: '2021-12-09T00:16:20Z'
              key: favoritemovie
              updated_at: '2021-12-09T00:16:23Z'
              value: Star Wars
              version: 2
              visibility: VISIBILITY_READ_WRITE_VALUES
            customer_id: SY8EMWRNDN3TQDP2H4KS1QWMMM
          id4:
            custom_attribute:
              created_at: '2021-12-08T23:14:47Z'
              key: square:a0f1505a-2aa1-490d-91a8-8d31ff181808
              updated_at: '2021-12-09T00:16:23Z'
              value: '10.5'
              version: 1
              visibility: VISIBILITY_READ_WRITE_VALUES
            customer_id: N3NCVYY3WS27HF0HKANA3R9FP8
          id5:
            custom_attribute:
              created_at: '2021-12-09T00:16:20Z'
              key: sq0ids-0evKIskIGaY45fCyNL66aw:backupemail
              updated_at: '2021-12-09T00:16:23Z'
              value: fake-email@squareup.com
              version: 2
              visibility: VISIBILITY_READ_WRITE_VALUES
            customer_id: 70548QG1HN43B05G0KCZ4MMC1G
    BulkUpsertCustomerCustomAttributesResponseCustomerCustomAttributeUpsertResponse:
      type: object
      description: >-
        Represents a response for an individual upsert request in a
        [BulkUpsertCustomerCustomAttributes](api-endpoint:CustomerCustomAttributes-BulkUpsertCustomerCustomAttributes)
        operation.
      x-release-status: PUBLIC
      properties:
        customer_id:
          type: string
          description: The ID of the customer profile associated with the custom attribute.
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: The new or updated custom attribute.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred while processing the individual request.
      example:
        custom_attribute:
          created_at: '2021-12-08T23:14:47Z'
          key: favoritemovie
          updated_at: '2021-12-09T00:16:23Z'
          value: Dune
          version: 1
          visibility: VISIBILITY_READ_WRITE_VALUES
        customer_id: N3NCVYY3WS27HF0HKANA3R9FP8
    BulkUpsertLocationCustomAttributesRequest:
      type: object
      description: >-
        Represents a
        [BulkUpsertLocationCustomAttributes](api-endpoint:LocationCustomAttributes-BulkUpsertLocationCustomAttributes)
        request.
      x-release-status: BETA
      required:
        - values
      properties:
        values:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/BulkUpsertLocationCustomAttributesRequestLocationCustomAttributeUpsertRequest
          description: >-
            A map containing 1 to 25 individual upsert requests. For each
            request, provide an

            arbitrary ID that is unique for this
            `BulkUpsertLocationCustomAttributes` request and the

            information needed to create or update a custom attribute.
      example:
        values:
          id1:
            custom_attribute:
              key: bestseller
              value: hot cocoa
            location_id: L0TBCBTB7P8RQ
          id2:
            custom_attribute:
              key: bestseller
              value: berry smoothie
            location_id: L9XMD04V3STJX
          id3:
            custom_attribute:
              key: phone-number
              value: '+12223334444'
            location_id: L0TBCBTB7P8RQ
    BulkUpsertLocationCustomAttributesRequestLocationCustomAttributeUpsertRequest:
      type: object
      description: >-
        Represents an individual upsert request in a
        [BulkUpsertLocationCustomAttributes](api-endpoint:LocationCustomAttributes-BulkUpsertLocationCustomAttributes)

        request. An individual request contains a location ID, the custom
        attribute to create or update,

        and an optional idempotency key.
      x-release-status: BETA
      required:
        - location_id
        - custom_attribute
      properties:
        location_id:
          type: string
          description: The ID of the target [location](entity:Location).
          minLength: 1
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The custom attribute to create or update, with following fields:

            - `key`. This key must match the `key` of a custom attribute
            definition in the Square seller

            account. If the requesting application is not the definition owner,
            you must provide the qualified key.

            - `value`. This value must conform to the `schema` specified by the
            definition.

            For more information, see [Supported data
            types](https://developer.squareup.com/docs/devtools/customattributes/overview#supported-data-types)..

            - `version`. To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control, specify the current version of the custom attribute. 

            If this is not important for your application, `version` can be set
            to -1.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this individual upsert request, used to
            ensure idempotency.

            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
          nullable: true
    BulkUpsertLocationCustomAttributesResponse:
      type: object
      description: >-
        Represents a
        [BulkUpsertLocationCustomAttributes](api-endpoint:LocationCustomAttributes-BulkUpsertLocationCustomAttributes)
        response,

        which contains a map of responses that each corresponds to an individual
        upsert request.
      x-release-status: BETA
      properties:
        values:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/BulkUpsertLocationCustomAttributesResponseLocationCustomAttributeUpsertResponse
          description: >-
            A map of responses that correspond to individual upsert requests.
            Each response has the

            same ID as the corresponding request and contains either a
            `location_id` and `custom_attribute` or an `errors` field.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        values:
          id1:
            custom_attribute:
              created_at: '2023-01-09T19:02:58.647Z'
              key: bestseller
              updated_at: '2023-01-09T19:21:04.551Z'
              value: hot cocoa
              version: 2
              visibility: VISIBILITY_READ_WRITE_VALUES
            location_id: L0TBCBTB7P8RQ
          id2:
            custom_attribute:
              created_at: '2023-01-09T19:02:58.647Z'
              key: bestseller
              updated_at: '2023-01-09T19:21:04.551Z'
              value: berry smoothie
              version: 1
              visibility: VISIBILITY_READ_WRITE_VALUES
            location_id: L9XMD04V3STJX
          id3:
            custom_attribute:
              created_at: '2023-01-09T19:04:57.985Z'
              key: phone-number
              updated_at: '2023-01-09T19:21:04.563Z'
              value: '+12239903892'
              version: 2
              visibility: VISIBILITY_READ_WRITE_VALUES
            location_id: L0TBCBTB7P8RQ
    BulkUpsertLocationCustomAttributesResponseLocationCustomAttributeUpsertResponse:
      type: object
      description: >-
        Represents a response for an individual upsert request in a
        [BulkUpsertLocationCustomAttributes](api-endpoint:LocationCustomAttributes-BulkUpsertLocationCustomAttributes)
        operation.
      x-release-status: BETA
      properties:
        location_id:
          type: string
          description: The ID of the location associated with the custom attribute.
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: The new or updated custom attribute.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred while processing the individual request.
      example:
        custom_attribute:
          created_at: '2023-01-09T19:02:58.647Z'
          key: bestseller
          updated_at: '2023-01-09T19:21:04.551Z'
          value: hot cocoa
          version: 2
          visibility: VISIBILITY_READ_WRITE_VALUES
        location_id: L0TBCBTB7P8RQ
    BulkUpsertMerchantCustomAttributesRequest:
      type: object
      description: >-
        Represents a
        [BulkUpsertMerchantCustomAttributes](api-endpoint:MerchantCustomAttributes-BulkUpsertMerchantCustomAttributes)
        request.
      x-release-status: BETA
      required:
        - values
      properties:
        values:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/BulkUpsertMerchantCustomAttributesRequestMerchantCustomAttributeUpsertRequest
          description: >-
            A map containing 1 to 25 individual upsert requests. For each
            request, provide an

            arbitrary ID that is unique for this
            `BulkUpsertMerchantCustomAttributes` request and the

            information needed to create or update a custom attribute.
      example:
        values:
          id1:
            custom_attribute:
              key: alternative_seller_name
              value: Ultimate Sneaker Store
            merchant_id: DM7VKY8Q63GNP
          id2:
            custom_attribute:
              key: has_seen_tutorial
              value: true
            merchant_id: DM7VKY8Q63GNP
    BulkUpsertMerchantCustomAttributesRequestMerchantCustomAttributeUpsertRequest:
      type: object
      description: >-
        Represents an individual upsert request in a
        [BulkUpsertMerchantCustomAttributes](api-endpoint:MerchantCustomAttributes-BulkUpsertMerchantCustomAttributes)

        request. An individual request contains a merchant ID, the custom
        attribute to create or update,

        and an optional idempotency key.
      x-release-status: BETA
      required:
        - merchant_id
        - custom_attribute
      properties:
        merchant_id:
          type: string
          description: The ID of the target [merchant](entity:Merchant).
          minLength: 1
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The custom attribute to create or update, with following fields:

            - `key`. This key must match the `key` of a custom attribute
            definition in the Square seller

            account. If the requesting application is not the definition owner,
            you must provide the qualified key.

            - `value`. This value must conform to the `schema` specified by the
            definition.

            For more information, see [Supported data
            types](https://developer.squareup.com/docs/devtools/customattributes/overview#supported-data-types).

            - The version field must match the current version of the custom
            attribute definition to enable

            [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            If this is not important for your application, version can be set to
            -1. For any other values, the request fails with a BAD_REQUEST
            error.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this individual upsert request, used to
            ensure idempotency.

            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
          nullable: true
    BulkUpsertMerchantCustomAttributesResponse:
      type: object
      description: >-
        Represents a
        [BulkUpsertMerchantCustomAttributes](api-endpoint:MerchantCustomAttributes-BulkUpsertMerchantCustomAttributes)
        response,

        which contains a map of responses that each corresponds to an individual
        upsert request.
      x-release-status: BETA
      properties:
        values:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/BulkUpsertMerchantCustomAttributesResponseMerchantCustomAttributeUpsertResponse
          description: >-
            A map of responses that correspond to individual upsert requests.
            Each response has the

            same ID as the corresponding request and contains either a
            `merchant_id` and `custom_attribute` or an `errors` field.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        values:
          id1:
            custom_attribute:
              created_at: '2023-05-06T19:02:58.647Z'
              key: alternative_seller_name
              updated_at: '2023-05-06T19:21:04.551Z'
              value: Ultimate Sneaker Store
              version: 2
              visibility: VISIBILITY_READ_ONLY
            merchant_id: DM7VKY8Q63GNP
          id2:
            custom_attribute:
              created_at: '2023-05-06T19:02:58.647Z'
              key: has_seen_tutorial
              updated_at: '2023-05-06T19:21:04.551Z'
              value: true
              version: 1
              visibility: VISIBILITY_READ_WRITE_VALUES
            merchant_id: DM7VKY8Q63GNP
    BulkUpsertMerchantCustomAttributesResponseMerchantCustomAttributeUpsertResponse:
      type: object
      description: >-
        Represents a response for an individual upsert request in a
        [BulkUpsertMerchantCustomAttributes](api-endpoint:MerchantCustomAttributes-BulkUpsertMerchantCustomAttributes)
        operation.
      x-release-status: BETA
      properties:
        merchant_id:
          type: string
          description: The ID of the merchant associated with the custom attribute.
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: The new or updated custom attribute.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred while processing the individual request.
      example:
        custom_attribute:
          created_at: '2023-05-06T19:02:58.647Z'
          key: alternative_seller_name
          updated_at: '2023-05-06T19:21:04.551Z'
          value: Ultimate Sneaker Store
          version: 2
          visibility: VISIBILITY_READ_ONLY
        merchant_id: DM7VKY8Q63GNP
    BulkUpsertOrderCustomAttributesRequest:
      type: object
      description: >-
        Represents a bulk upsert request for one or more order custom
        attributes.
      x-release-status: BETA
      required:
        - values
      properties:
        values:
          type: object
          additionalProperties:
            $ref: >-
              #/components/schemas/BulkUpsertOrderCustomAttributesRequestUpsertCustomAttribute
          description: >-
            A map of requests that correspond to individual upsert operations
            for custom attributes.
      example:
        values:
          cover-count:
            custom_attribute:
              key: cover-count
              value: '6'
              version: 2
            order_id: 7BbXGEIWNldxAzrtGf9GPVZTwZ4F
          table-number:
            custom_attribute:
              key: table-number
              value: '11'
              version: 4
            order_id: 7BbXGEIWNldxAzrtGf9GPVZTwZ4F
    BulkUpsertOrderCustomAttributesRequestUpsertCustomAttribute:
      type: object
      description: Represents one upsert within the bulk operation.
      x-release-status: BETA
      required:
        - custom_attribute
        - order_id
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The custom attribute to create or update, with the following fields:


            - `value`. This value must conform to the `schema` specified by the
            definition. 

            For more information, see [Value data
            types](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attributes#value-data-types).


            - `version`. To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control, include this optional field and specify the current version
            of the custom attribute.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency. 

            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          minLength: 1
          maxLength: 45
          nullable: true
        order_id:
          type: string
          description: The ID of the target [order](entity:Order).
          minLength: 1
          maxLength: 255
    BulkUpsertOrderCustomAttributesResponse:
      type: object
      description: Represents a response from a bulk upsert of order custom attributes.
      x-release-status: BETA
      required:
        - values
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        values:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/UpsertOrderCustomAttributeResponse'
          description: ' A map of responses that correspond to individual upsert operations for custom attributes.'
      example:
        values:
          cover-count:
            custom_attribute:
              created_at: '2022-11-22T21:27:33.429Z'
              key: cover-count
              updated_at: '2022-11-22T21:28:35.721Z'
              value: '6'
              visibility: VISIBILITY_READ_WRITE_VALUES
          table-number:
            custom_attribute:
              created_at: '2022-11-22T21:24:57.823Z'
              key: table-number
              updated_at: '2022-11-22T21:28:35.726Z'
              value: '11'
              visibility: VISIBILITY_HIDDEN
    BusinessAppointmentSettings:
      type: object
      description: >-
        The service appointment settings, including where and how the service is
        provided.
      x-release-status: PUBLIC
      properties:
        location_types:
          type: array
          items:
            $ref: >-
              #/components/schemas/BusinessAppointmentSettingsBookingLocationType
          description: >-
            Types of the location allowed for bookings.

            See
            [BusinessAppointmentSettingsBookingLocationType](#type-businessappointmentsettingsbookinglocationtype)
            for possible values
          nullable: true
        alignment_time:
          $ref: '#/components/schemas/BusinessAppointmentSettingsAlignmentTime'
          description: >-
            The time unit of the service duration for bookings.

            See
            [BusinessAppointmentSettingsAlignmentTime](#type-businessappointmentsettingsalignmenttime)
            for possible values
          nullable: true
        min_booking_lead_time_seconds:
          type: integer
          description: >-
            The minimum lead time in seconds before a service can be booked. A
            booking must be created at least this amount of time before its
            starting time.
          nullable: true
        max_booking_lead_time_seconds:
          type: integer
          description: >-
            The maximum lead time in seconds before a service can be booked. A
            booking must be created at most this amount of time before its
            starting time.
          nullable: true
        any_team_member_booking_enabled:
          type: boolean
          description: >-
            Indicates whether a customer can choose from all available time
            slots and have a staff member assigned

            automatically (`true`) or not (`false`).
          nullable: true
        multiple_service_booking_enabled:
          type: boolean
          description: >-
            Indicates whether a customer can book multiple services in a single
            online booking.
          nullable: true
        max_appointments_per_day_limit_type:
          $ref: >-
            #/components/schemas/BusinessAppointmentSettingsMaxAppointmentsPerDayLimitType
          description: >-
            Indicates whether the daily appointment limit applies to team
            members or to

            business locations.

            See
            [BusinessAppointmentSettingsMaxAppointmentsPerDayLimitType](#type-businessappointmentsettingsmaxappointmentsperdaylimittype)
            for possible values
          nullable: true
        max_appointments_per_day_limit:
          type: integer
          description: >-
            The maximum number of daily appointments per team member or per
            location.
          nullable: true
        cancellation_window_seconds:
          type: integer
          description: >-
            The cut-off time in seconds for allowing clients to cancel or
            reschedule an appointment.
          nullable: true
        cancellation_fee_money:
          $ref: '#/components/schemas/Money'
          description: The flat-fee amount charged for a no-show booking.
          nullable: true
        cancellation_policy:
          $ref: '#/components/schemas/BusinessAppointmentSettingsCancellationPolicy'
          description: >-
            The cancellation policy adopted by the seller.

            See
            [BusinessAppointmentSettingsCancellationPolicy](#type-businessappointmentsettingscancellationpolicy)
            for possible values
          nullable: true
        cancellation_policy_text:
          type: string
          description: The free-form text of the seller's cancellation policy.
          maxLength: 65536
          nullable: true
        skip_booking_flow_staff_selection:
          type: boolean
          description: >-
            Indicates whether customers has an assigned staff member (`true`) or
            can select s staff member of their choice (`false`).
          nullable: true
    BusinessAppointmentSettingsAlignmentTime:
      type: string
      enum:
        - SERVICE_DURATION
        - QUARTER_HOURLY
        - HALF_HOURLY
        - HOURLY
      x-enum-elements:
        - name: SERVICE_DURATION
          description: >-
            The service duration unit is one visit of a fixed time interval
            specified by the seller.
        - name: QUARTER_HOURLY
          description: >-
            The service duration unit is a 15-minute interval. Bookings can be
            scheduled every quarter hour.
        - name: HALF_HOURLY
          description: >-
            The service duration unit is a 30-minute interval. Bookings can be
            scheduled every half hour.
        - name: HOURLY
          description: >-
            The service duration unit is a 60-minute interval. Bookings can be
            scheduled every hour.
      description: Time units of a service duration for bookings.
      x-release-status: PUBLIC
    BusinessAppointmentSettingsBookingLocationType:
      type: string
      enum:
        - BUSINESS_LOCATION
        - CUSTOMER_LOCATION
        - PHONE
      x-enum-elements:
        - name: BUSINESS_LOCATION
          description: The service is provided at a seller location.
        - name: CUSTOMER_LOCATION
          description: The service is provided at a customer location.
        - name: PHONE
          description: The service is provided over the phone.
      description: Supported types of location where service is provided.
      x-release-status: PUBLIC
    BusinessAppointmentSettingsCancellationPolicy:
      type: string
      enum:
        - CANCELLATION_TREATED_AS_NO_SHOW
        - CUSTOM_POLICY
      x-enum-elements:
        - name: CANCELLATION_TREATED_AS_NO_SHOW
          description: >-
            Cancellations are treated as no shows and may incur a fee as
            specified by `cancellation_fee_money`.
        - name: CUSTOM_POLICY
          description: >-
            Cancellations follow the seller-specified policy that is described
            in free-form text and not enforced automatically by Square.
      description: The category of the sellers cancellation policy.
      x-release-status: PUBLIC
    BusinessAppointmentSettingsMaxAppointmentsPerDayLimitType:
      type: string
      enum:
        - PER_TEAM_MEMBER
        - PER_LOCATION
      x-enum-elements:
        - name: PER_TEAM_MEMBER
          description: >-
            The maximum number of daily appointments is set on a per team member
            basis.
        - name: PER_LOCATION
          description: >-
            The maximum number of daily appointments is set on a per location
            basis.
      description: Types of daily appointment limits.
      x-release-status: PUBLIC
    BusinessBookingProfile:
      type: object
      description: >-
        A seller's business booking profile, including booking policy,
        appointment settings, etc.
      x-release-status: PUBLIC
      properties:
        seller_id:
          type: string
          description: The ID of the seller, obtainable using the Merchants API.
          maxLength: 32
          nullable: true
        created_at:
          type: string
          description: The RFC 3339 timestamp specifying the booking's creation time.
          readOnly: true
        booking_enabled:
          type: boolean
          description: Indicates whether the seller is open for booking.
          nullable: true
        customer_timezone_choice:
          $ref: '#/components/schemas/BusinessBookingProfileCustomerTimezoneChoice'
          description: >-
            The choice of customer's time zone information of a booking.

            The Square online booking site and all notifications to customers
            uses either the seller locations time zone

            or the time zone the customer chooses at booking.

            See
            [BusinessBookingProfileCustomerTimezoneChoice](#type-businessbookingprofilecustomertimezonechoice)
            for possible values
          nullable: true
        booking_policy:
          $ref: '#/components/schemas/BusinessBookingProfileBookingPolicy'
          description: >-
            The policy for the seller to automatically accept booking requests
            (`ACCEPT_ALL`) or not (`REQUIRES_ACCEPTANCE`).

            See
            [BusinessBookingProfileBookingPolicy](#type-businessbookingprofilebookingpolicy)
            for possible values
          nullable: true
        allow_user_cancel:
          type: boolean
          description: >-
            Indicates whether customers can cancel or reschedule their own
            bookings (`true`) or not (`false`).
          nullable: true
        business_appointment_settings:
          $ref: '#/components/schemas/BusinessAppointmentSettings'
          description: Settings for appointment-type bookings.
          nullable: true
        support_seller_level_writes:
          type: boolean
          description: >-
            Indicates whether the seller's subscription to Square Appointments
            supports creating, updating or canceling an appointment through the
            API (`true`) or not (`false`) using seller permission.
          nullable: true
    BusinessBookingProfileBookingPolicy:
      type: string
      enum:
        - ACCEPT_ALL
        - REQUIRES_ACCEPTANCE
      x-enum-elements:
        - name: ACCEPT_ALL
          description: The seller accepts all booking requests automatically.
        - name: REQUIRES_ACCEPTANCE
          description: The seller must accept requests to complete bookings.
      description: Policies for accepting bookings.
      x-release-status: PUBLIC
    BusinessBookingProfileCustomerTimezoneChoice:
      type: string
      enum:
        - BUSINESS_LOCATION_TIMEZONE
        - CUSTOMER_CHOICE
      x-enum-elements:
        - name: BUSINESS_LOCATION_TIMEZONE
          description: Use the time zone of the business location for bookings.
        - name: CUSTOMER_CHOICE
          description: Use the customer-chosen time zone for bookings.
      description: Choices of customer-facing time zone used for bookings.
      x-release-status: PUBLIC
    BusinessHours:
      type: object
      description: The hours of operation for a location.
      x-release-status: PUBLIC
      properties:
        periods:
          type: array
          items:
            $ref: '#/components/schemas/BusinessHoursPeriod'
          description: >-
            The list of time periods during which the business is open. There
            can be at most 10 periods per day.
          nullable: true
    BusinessHoursPeriod:
      type: object
      description: Represents a period of time during which a business location is open.
      x-release-status: PUBLIC
      properties:
        day_of_week:
          $ref: '#/components/schemas/DayOfWeek'
          description: |-
            The day of the week for this time period.
            See [DayOfWeek](#type-dayofweek) for possible values
          nullable: true
        start_local_time:
          type: string
          description: >-
            The start time of a business hours period, specified in local time
            using partial-time

            RFC 3339 format. For example, `8:30:00` for a period starting at
            8:30 in the morning.

            Note that the seconds value is always :00, but it is appended for
            conformance to the RFC.
          nullable: true
        end_local_time:
          type: string
          description: >-
            The end time of a business hours period, specified in local time
            using partial-time

            RFC 3339 format. For example, `21:00:00` for a period ending at 9:00
            in the evening.

            Note that the seconds value is always :00, but it is appended for
            conformance to the RFC.
          nullable: true
    BuyNowPayLaterDetails:
      type: object
      description: Additional details about a Buy Now Pay Later payment type.
      x-release-status: PUBLIC
      properties:
        brand:
          type: string
          description: |-
            The brand used for the Buy Now Pay Later payment.
            The brand can be `AFTERPAY`, `CLEARPAY` or `UNKNOWN`.
          maxLength: 50
          nullable: true
        afterpay_details:
          $ref: '#/components/schemas/AfterpayDetails'
          description: >-
            Details about an Afterpay payment. These details are only populated
            if the `brand` is

            `AFTERPAY`.
          nullable: true
        clearpay_details:
          $ref: '#/components/schemas/ClearpayDetails'
          description: >-
            Details about a Clearpay payment. These details are only populated
            if the `brand` is

            `CLEARPAY`.
          nullable: true
    CalculateLoyaltyPointsRequest:
      type: object
      description: >-
        Represents a
        [CalculateLoyaltyPoints](api-endpoint:Loyalty-CalculateLoyaltyPoints)
        request.
      x-release-status: PUBLIC
      x-params-example: '?program_id=d619f755-2d17-41f3-990d-c04ecedd64dd'
      properties:
        order_id:
          type: string
          description: >-
            The [order](entity:Order) ID for which to calculate the points.

            Specify this field if your application uses the Orders API to
            process orders.

            Otherwise, specify the `transaction_amount_money`.
          nullable: true
        transaction_amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The purchase amount for which to calculate the points. 

            Specify this field if your application does not use the Orders API
            to process orders.

            Otherwise, specify the `order_id`.
          nullable: true
        loyalty_account_id:
          type: string
          description: >-
            The ID of the target [loyalty account](entity:LoyaltyAccount).
            Optionally specify this field

            if your application uses the Orders API to process orders.


            If specified, the `promotion_points` field in the response shows the
            number of points the buyer would

            earn from the purchase. In this case, Square uses the account ID to
            determine whether the promotion's

            `trigger_limit` (the maximum number of times that a buyer can
            trigger the promotion) has been reached.

            If not specified, the `promotion_points` field shows the number of
            points the purchase qualifies

            for regardless of the trigger limit.
          minLength: 1
          maxLength: 36
          nullable: true
      example:
        loyalty_account_id: 79b807d2-d786-46a9-933b-918028d7a8c5
        order_id: RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY
    CalculateLoyaltyPointsResponse:
      type: object
      description: >-
        Represents a
        [CalculateLoyaltyPoints](api-endpoint:Loyalty-CalculateLoyaltyPoints)
        response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        points:
          type: integer
          description: >-
            The number of points that the buyer can earn from the base loyalty
            program.
        promotion_points:
          type: integer
          description: >-
            The number of points that the buyer can earn from a loyalty
            promotion. To be eligible

            to earn promotion points, the purchase must first qualify for
            program points. When `order_id`

            is not provided in the request, this value is always 0.
      example:
        points: 6
        promotion_points: 12
    CalculateOrderRequest:
      type: object
      x-release-status: BETA
      required:
        - order
      properties:
        order:
          $ref: '#/components/schemas/Order'
          description: >-
            The order to be calculated. Expects the entire order, not a sparse
            update.
        proposed_rewards:
          type: array
          items:
            $ref: '#/components/schemas/OrderReward'
          description: >-
            Identifies one or more loyalty reward tiers to apply during the
            order calculation.

            The discounts defined by the reward tiers are added to the order
            only to preview the

            effect of applying the specified rewards. The rewards do not
            correspond to actual

            redemptions; that is, no `reward`s are created. Therefore, the
            reward `id`s are

            random strings used only to reference the reward tier.
          nullable: true
      example:
        idempotency_key: b3e98fe3-b8de-471c-82f1-545f371e637c
        order:
          discounts:
            - name: 50% Off
              percentage: '50'
              scope: ORDER
          line_items:
            - base_price_money:
                amount: 500
                currency: USD
              name: Item 1
              quantity: '1'
            - base_price_money:
                amount: 300
                currency: USD
              name: Item 2
              quantity: '2'
          location_id: D7AVYMEAPJ3A3
    CalculateOrderResponse:
      type: object
      x-release-status: BETA
      properties:
        order:
          $ref: '#/components/schemas/Order'
          description: The calculated version of the order provided in the request.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        order:
          created_at: '2020-05-18T16:30:49.614Z'
          discounts:
            - applied_money:
                amount: 550
                currency: USD
              name: 50% Off
              percentage: '50'
              scope: ORDER
              type: FIXED_PERCENTAGE
              uid: zGsRZP69aqSSR9lq9euSPB
          line_items:
            - applied_discounts:
                - applied_money:
                    amount: 250
                    currency: USD
                  discount_uid: zGsRZP69aqSSR9lq9euSPB
                  uid: 9zr9S4dxvPAixvn0lpa1VC
              base_price_money:
                amount: 500
                currency: USD
              gross_sales_money:
                amount: 500
                currency: USD
              name: Item 1
              quantity: '1'
              total_discount_money:
                amount: 250
                currency: USD
              total_money:
                amount: 250
                currency: USD
              total_service_charge_money:
                amount: 0
                currency: USD
              total_tax_money:
                amount: 0
                currency: USD
              uid: ULkg0tQTRK2bkU9fNv3IJD
              variation_total_price_money:
                amount: 500
                currency: USD
            - applied_discounts:
                - applied_money:
                    amount: 300
                    currency: USD
                  discount_uid: zGsRZP69aqSSR9lq9euSPB
                  uid: qa8LwwZK82FgSEkQc2HYVC
              base_price_money:
                amount: 300
                currency: USD
              gross_sales_money:
                amount: 600
                currency: USD
              name: Item 2
              quantity: '2'
              total_discount_money:
                amount: 300
                currency: USD
              total_money:
                amount: 300
                currency: USD
              total_service_charge_money:
                amount: 0
                currency: USD
              total_tax_money:
                amount: 0
                currency: USD
              uid: mumY8Nun4BC5aKe2yyx5a
              variation_total_price_money:
                amount: 600
                currency: USD
          location_id: D7AVYMEAPJ3A3
          net_amounts:
            discount_money:
              amount: 550
              currency: USD
            service_charge_money:
              amount: 0
              currency: USD
            tax_money:
              amount: 0
              currency: USD
            tip_money:
              amount: 0
              currency: USD
            total_money:
              amount: 550
              currency: USD
          state: OPEN
          total_discount_money:
            amount: 550
            currency: USD
          total_money:
            amount: 550
            currency: USD
          total_service_charge_money:
            amount: 0
            currency: USD
          total_tax_money:
            amount: 0
            currency: USD
          total_tip_money:
            amount: 0
            currency: USD
          updated_at: '2020-05-18T16:30:49.614Z'
          version: 1
    CancelBookingRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        idempotency_key:
          type: string
          description: A unique key to make this request an idempotent operation.
          maxLength: 255
          nullable: true
        booking_version:
          type: integer
          description: The revision number for the booking used for optimistic concurrency.
          nullable: true
    CancelBookingResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        booking:
          $ref: '#/components/schemas/Booking'
          description: The booking that was cancelled.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
      example:
        booking:
          appointment_segments:
            - duration_minutes: 60
              service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
              service_variation_version: 1599775456731
              team_member_id: TMXUrsBWWcHTt79t
          created_at: '2020-10-28T15:47:41Z'
          customer_id: EX2QSVGTZN4K1E5QE1CBFNVQ8M
          customer_note: ''
          id: zkras0xv0xwswx
          location_id: LEQHH0YY8B42M
          seller_note: ''
          start_at: '2020-11-26T13:00:00Z'
          status: CANCELLED_BY_CUSTOMER
          updated_at: '2020-10-28T15:49:25Z'
          version: 1
        errors: []
    CancelInvoiceRequest:
      type: object
      description: Describes a `CancelInvoice` request.
      x-release-status: PUBLIC
      required:
        - version
      properties:
        version:
          type: integer
          description: >-
            The version of the [invoice](entity:Invoice) to cancel.

            If you do not know the version, you can call 

            [GetInvoice](api-endpoint:Invoices-GetInvoice) or
            [ListInvoices](api-endpoint:Invoices-ListInvoices).
      example:
        version: 0
    CancelInvoiceResponse:
      type: object
      description: The response returned by the `CancelInvoice` request.
      x-release-status: PUBLIC
      properties:
        invoice:
          $ref: '#/components/schemas/Invoice'
          description: The canceled invoice.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example:
        invoice:
          accepted_payment_methods:
            bank_account: false
            buy_now_pay_later: false
            card: true
            cash_app_pay: false
            square_gift_card: false
          created_at: '2020-06-18T17:45:13Z'
          custom_fields:
            - label: Event Reference Number
              placement: ABOVE_LINE_ITEMS
              value: 'Ref. #1234'
            - label: Terms of Service
              placement: BELOW_LINE_ITEMS
              value: The terms of service are...
          delivery_method: EMAIL
          description: We appreciate your business!
          id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
          invoice_number: inv-100
          location_id: ES0RJRZYEC39A
          order_id: CAISENgvlJ6jLWAzERDzjyHVybY
          payment_requests:
            - automatic_payment_source: NONE
              computed_amount_money:
                amount: 10000
                currency: USD
              due_date: '2030-01-24'
              reminders:
                - message: Your invoice is due tomorrow
                  relative_scheduled_days: -1
                  status: PENDING
                  uid: beebd363-e47f-4075-8785-c235aaa7df11
              request_type: BALANCE
              tipping_enabled: true
              total_completed_amount_money:
                amount: 0
                currency: USD
              uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355
          primary_recipient:
            customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4
            email_address: Amelia.Earhart@example.com
            family_name: Earhart
            given_name: Amelia
            phone_number: 1-212-555-4240
          sale_or_service_date: '2030-01-24'
          scheduled_at: '2030-01-13T10:00:00Z'
          status: CANCELED
          store_payment_method_enabled: false
          timezone: America/Los_Angeles
          title: Event Planning Services
          updated_at: '2020-06-18T18:23:11Z'
          version: 1
    CancelLoyaltyPromotionRequest:
      type: object
      description: >-
        Represents a
        [CancelLoyaltyPromotion](api-endpoint:Loyalty-CancelLoyaltyPromotion)
        request.
      x-release-status: PUBLIC
      x-params-example: >-
        ?program_id=d619f755-2d17-41f3-990d-c04ecedd64dd&promotion_id=loypromo_f0f9b849-725e-378d-b810-511237e07b67
      properties: {}
      example: {}
    CancelLoyaltyPromotionResponse:
      type: object
      description: >-
        Represents a
        [CancelLoyaltyPromotion](api-endpoint:Loyalty-CancelLoyaltyPromotion)
        response.

        Either `loyalty_promotion` or `errors` is present in the response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        loyalty_promotion:
          $ref: '#/components/schemas/LoyaltyPromotion'
          description: The canceled loyalty promotion.
      example:
        loyalty_promotion:
          available_time:
            start_date: '2022-08-16'
            time_periods:
              - |-
                BEGIN:VEVENT
                DTSTART:20220816T160000
                DURATION:PT2H
                RRULE:FREQ=WEEKLY;BYDAY=TU
                END:VEVENT
          canceled_at: '2022-08-17T12:42:49Z'
          created_at: '2022-08-16T08:38:54Z'
          id: loypromo_f0f9b849-725e-378d-b810-511237e07b67
          incentive:
            points_multiplier_data:
              multiplier: '3.000'
              points_multiplier: 3
            type: POINTS_MULTIPLIER
          loyalty_program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
          minimum_spend_amount_money:
            amount: 2000
            currency: USD
          name: Tuesday Happy Hour Promo
          qualifying_category_ids:
            - XTQPYLR3IIU9C44VRCB3XD12
          status: CANCELED
          trigger_limit:
            interval: DAY
            times: 1
          updated_at: '2022-08-17T12:42:49Z'
    CancelPaymentByIdempotencyKeyRequest:
      type: object
      description: >-
        Describes a request to cancel a payment using 

        [CancelPaymentByIdempotencyKey](api-endpoint:Payments-CancelPaymentByIdempotencyKey).
      x-release-status: PUBLIC
      required:
        - idempotency_key
      properties:
        idempotency_key:
          type: string
          description: The `idempotency_key` identifying the payment to be canceled.
          minLength: 1
          maxLength: 45
      example:
        idempotency_key: a7e36d40-d24b-11e8-b568-0800200c9a66
    CancelPaymentByIdempotencyKeyResponse:
      type: object
      description: >-
        Defines the response returned by 

        [CancelPaymentByIdempotencyKey](api-endpoint:Payments-CancelPaymentByIdempotencyKey).

        On success, `errors` is empty.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    CancelPaymentRequest:
      type: object
      description: >-
        Describes the request to cancel (void) a payment using

        [CancelPayment](api-endpoint:Payments-CancelPayment).

        You can only cancel a payment that is approved (not completed).

        For more information, see

        [Delayed capture of a
        payment](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment).
      x-release-status: PUBLIC
      properties: {}
      example: {}
    CancelPaymentResponse:
      type: object
      description: >-
        Defines the response returned by
        [CancelPayment](api-endpoint:Payments-CancelPayment).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        payment:
          $ref: '#/components/schemas/Payment'
          description: The successfully canceled `Payment` object.
      example:
        payment:
          amount_money:
            amount: 1000
            currency: USD
          application_details:
            application_id: sq0ids-TcgftTEtKxJTRF1lCFJ9TA
            square_product: ECOMMERCE_API
          approved_money:
            amount: 1000
            currency: USD
          card_details:
            auth_result_code: 68aLBM
            avs_status: AVS_ACCEPTED
            card:
              bin: '411111'
              card_brand: VISA
              card_type: DEBIT
              exp_month: 11
              exp_year: 2022
              fingerprint: >-
                sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ
              last_4: '1111'
              prepaid_type: NOT_PREPAID
            card_payment_timeline:
              authorized_at: '2021-10-13T20:26:44.364Z'
              voided_at: '2021-10-13T20:31:21.597Z'
            cvv_status: CVV_ACCEPTED
            entry_method: ON_FILE
            statement_description: SQ *EXAMPLE TEST GOSQ.C
            status: VOIDED
          created_at: '2021-10-13T20:26:44.191Z'
          customer_id: W92WH6P11H4Z77CTET0RNTGFW8
          delay_action: CANCEL
          delay_duration: PT168H
          delayed_until: '2021-10-20T20:26:44.191Z'
          id: 1QjqpBVyrI9S4H9sTGDWU9JeiWdZY
          location_id: L88917AVBK2S5
          note: Example Note
          order_id: nUSN9TdxpiK3SrQg3wzmf6r8LP9YY
          risk_evaluation:
            created_at: '2021-10-13T20:26:45.271Z'
            risk_level: NORMAL
          source_type: CARD
          status: CANCELED
          tip_money:
            amount: 100
            currency: USD
          total_money:
            amount: 1100
            currency: USD
          updated_at: '2021-10-13T20:31:21.597Z'
          version_token: N8AGYgEjCiY9Q57Jw7aVHEpBq8bzGCDCQMRX8Vs56N06o
    CancelSubscriptionRequest:
      type: object
      description: >-
        Defines input parameters in a request to the 

        [CancelSubscription](api-endpoint:Subscriptions-CancelSubscription)
        endpoint.
      x-release-status: PUBLIC
      properties: {}
    CancelSubscriptionResponse:
      type: object
      description: >-
        Defines output parameters in a response from the 

        [CancelSubscription](api-endpoint:Subscriptions-CancelSubscription)
        endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered during the request.
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: >-
            The specified subscription scheduled for cancellation according to
            the action created by the request.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionAction'
          description: A list of a single `CANCEL` action scheduled for the subscription.
          x-release-status: BETA
      example:
        subscription:
          canceled_date: '2023-06-05'
          card_id: ccof:qy5x8hHGYsgLrp4Q4GB
          created_at: '2022-01-19T21:53:10Z'
          customer_id: CHFGVKYY8RSV93M5KCYTG4PN0G
          id: 910afd30-464a-4e00-a8d8-2296e
          invoice_ids:
            - inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
            - inv:0-ChrcX_i3sNmfsHTGKhI4Wg2mceA
          location_id: S8GWD5R9QB376
          paid_until_date: '2023-12-31'
          plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
          source:
            name: My Application
          start_date: '2022-01-19'
          status: ACTIVE
          timezone: America/Los_Angeles
          version: 3
    CancelTerminalActionRequest:
      type: object
      x-release-status: BETA
      properties: {}
      example: {}
    CancelTerminalActionResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        action:
          $ref: '#/components/schemas/TerminalAction'
          description: The canceled `TerminalAction`
      example:
        action:
          app_id: APP_ID
          cancel_reason: SELLER_CANCELED
          created_at: '2021-07-28T23:22:07.476Z'
          deadline_duration: PT5M
          device_id: DEVICE_ID
          id: termapia:jveJIAkkAjILHkdCE
          location_id: LOCATION_ID
          save_card_options:
            customer_id: CUSTOMER_ID
            reference_id: user-id-1
          status: CANCELED
          type: SAVE_CARD
          updated_at: '2021-07-28T23:22:29.511Z'
    CancelTerminalCheckoutRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
      example: {}
    CancelTerminalCheckoutResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        checkout:
          $ref: '#/components/schemas/TerminalCheckout'
          description: The canceled `TerminalCheckout`.
      example:
        checkout:
          amount_money:
            amount: 123
            currency: USD
          app_id: APP_ID
          cancel_reason: SELLER_CANCELED
          created_at: '2020-03-16T15:31:19.934Z'
          deadline_duration: PT5M
          device_options:
            device_id: dbb5d83a-7838-11ea-bc55-0242ac130003
            skip_receipt_screen: true
            tip_settings:
              allow_tipping: true
          id: S1yDlPQx7slqO
          location_id: LOCATION_ID
          reference_id: id36815
          status: CANCELED
          updated_at: '2020-03-16T15:31:45.787Z'
    CancelTerminalRefundRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
      example: {}
    CancelTerminalRefundResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        refund:
          $ref: '#/components/schemas/TerminalRefund'
          description: The updated `TerminalRefund`.
      example:
        refund:
          amount_money:
            amount: 100
            currency: CAD
          app_id: sandbox-sq0idb-c2OuYt13YaCAeJq_2cd8OQ
          cancel_reason: SELLER_CANCELED
          card:
            bin: '411111'
            card_brand: INTERAC
            card_type: CREDIT
            exp_month: 1
            exp_year: 2022
            fingerprint: >-
              sq-1-B1fP9MNNmZgVVaPKRND6oDKYbz25S2cTvg9Mzwg3RMTK1zT1PiGRT-AE3nTA8vSmmw
            last_4: '1111'
          created_at: '2020-10-21T22:47:23.241Z'
          deadline_duration: PT5M
          device_id: 42690809-faa2-4701-a24b-19d3d34c9aaa
          id: g6ycb6HD-5O5OvgkcNUhl7JBuINflcjKqUzXZY
          location_id: 76C9W6K8CNNQ5
          order_id: kcuKDKreRaI4gF4TjmEgZjHk8Z7YY
          payment_id: 5O5OvgkcNUhl7JBuINflcjKqUzXZY
          reason: reason
          status: CANCELED
          updated_at: '2020-10-21T22:47:30.096Z'
    CaptureTransactionRequest:
      type: object
      x-release-status: DEPRECATED
      properties: {}
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/CaptureTransaction/CaptureTransactionRequest.csharp
        java: /sdk_samples/CaptureTransaction/CaptureTransactionRequest.java
        javascript: /sdk_samples/CaptureTransaction/CaptureTransactionRequest.javascript
        php: /sdk_samples/CaptureTransaction/CaptureTransactionRequest.php
        python: /sdk_samples/CaptureTransaction/CaptureTransactionRequest.python
        ruby: /sdk_samples/CaptureTransaction/CaptureTransactionRequest.ruby
    CaptureTransactionResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [CaptureTransaction](api-endpoint:Transactions-CaptureTransaction)
        endpoint.
      x-release-status: DEPRECATED
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/CaptureTransaction/CaptureTransactionResponse.csharp
        java: /sdk_samples/CaptureTransaction/CaptureTransactionResponse.java
        javascript: /sdk_samples/CaptureTransaction/CaptureTransactionResponse.javascript
        php: /sdk_samples/CaptureTransaction/CaptureTransactionResponse.php
        python: /sdk_samples/CaptureTransaction/CaptureTransactionResponse.python
        ruby: /sdk_samples/CaptureTransaction/CaptureTransactionResponse.ruby
    Card:
      type: object
      description: >-
        Represents the payment details of a card to be used for payments. These

        details are determined by the payment token generated by Web Payments
        SDK.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: Unique ID for this card. Generated by Square.
          maxLength: 64
          readOnly: true
        card_brand:
          $ref: '#/components/schemas/CardBrand'
          description: |-
            The card's brand.
            See [CardBrand](#type-cardbrand) for possible values
          readOnly: true
        last_4:
          type: string
          description: The last 4 digits of the card number.
          maxLength: 4
          readOnly: true
        exp_month:
          type: integer
          description: >-
            The expiration month of the associated card as an integer between 1
            and 12.
          format: int64
          nullable: true
        exp_year:
          type: integer
          description: The four-digit year of the card's expiration date.
          format: int64
          nullable: true
        cardholder_name:
          type: string
          description: The name of the cardholder.
          maxLength: 96
          nullable: true
        billing_address:
          $ref: '#/components/schemas/Address'
          description: The billing address for this card.
          nullable: true
        fingerprint:
          type: string
          description: >-
            Intended as a Square-assigned identifier, based

            on the card number, to identify the card across multiple locations
            within a

            single application.
          maxLength: 255
          readOnly: true
        customer_id:
          type: string
          description: >-
            **Required** The ID of a customer created using the Customers API to
            be associated with the card.
          nullable: true
        merchant_id:
          type: string
          description: The ID of the merchant associated with the card.
          readOnly: true
        reference_id:
          type: string
          description: >-
            An optional user-defined reference ID that associates this card with

            another entity in an external system. For example, a customer ID
            from an

            external customer management system.
          maxLength: 128
          nullable: true
        enabled:
          type: boolean
          description: Indicates whether or not a card can be used for payments.
          readOnly: true
        card_type:
          $ref: '#/components/schemas/CardType'
          description: >-
            The type of the card.

            The Card object includes this field only in response to Payments API
            calls.

            See [CardType](#type-cardtype) for possible values
          readOnly: true
        prepaid_type:
          $ref: '#/components/schemas/CardPrepaidType'
          description: >-
            Indicates whether the Card is prepaid or not.

            The Card object includes this field only in response to Payments API
            calls.

            See [CardPrepaidType](#type-cardprepaidtype) for possible values
          readOnly: true
        bin:
          type: string
          description: >-
            The first six digits of the card number, known as the Bank
            Identification Number (BIN). Only the Payments API

            returns this field.
          maxLength: 6
          readOnly: true
        version:
          type: integer
          description: >-
            Current version number of the card. Increments with each card
            update. Requests to update an

            existing Card object will be rejected unless the version in the
            request matches the current

            version for the Card.
          format: int64
        card_co_brand:
          $ref: '#/components/schemas/CardCoBrand'
          description: >-
            The card's co-brand if available. For example, an Afterpay virtual
            card would have a

            co-brand of AFTERPAY.

            See [CardCoBrand](#type-cardcobrand) for possible values
          readOnly: true
    CardBrand:
      type: string
      enum:
        - OTHER_BRAND
        - VISA
        - MASTERCARD
        - AMERICAN_EXPRESS
        - DISCOVER
        - DISCOVER_DINERS
        - JCB
        - CHINA_UNIONPAY
        - SQUARE_GIFT_CARD
        - SQUARE_CAPITAL_CARD
        - INTERAC
        - EFTPOS
        - FELICA
        - EBT
      x-enum-elements:
        - name: OTHER_BRAND
          description: ''
        - name: VISA
          description: ''
        - name: MASTERCARD
          description: ''
        - name: AMERICAN_EXPRESS
          description: ''
        - name: DISCOVER
          description: ''
        - name: DISCOVER_DINERS
          description: ''
        - name: JCB
          description: ''
        - name: CHINA_UNIONPAY
          description: ''
        - name: SQUARE_GIFT_CARD
          description: ''
        - name: SQUARE_CAPITAL_CARD
          description: ''
        - name: INTERAC
          description: ''
        - name: EFTPOS
          description: ''
        - name: FELICA
          description: ''
        - name: EBT
          description: ''
      description: Indicates a card's brand, such as `VISA` or `MASTERCARD`.
      x-release-status: PUBLIC
    CardCoBrand:
      type: string
      enum:
        - UNKNOWN
        - AFTERPAY
        - CLEARPAY
      x-enum-elements:
        - name: UNKNOWN
          description: ''
        - name: AFTERPAY
          description: ''
        - name: CLEARPAY
          description: ''
      description: Indicates the brand for a co-branded card.
      x-release-status: PUBLIC
    CardPaymentDetails:
      type: object
      description: >-
        Reflects the current status of a card payment. Contains only
        non-confidential information.
      x-release-status: PUBLIC
      properties:
        status:
          type: string
          description: >-
            The card payment's current state. The state can be AUTHORIZED,
            CAPTURED, VOIDED, or

            FAILED.
          maxLength: 50
          nullable: true
        card:
          $ref: '#/components/schemas/Card'
          description: The credit card's non-confidential details.
          nullable: true
        entry_method:
          type: string
          description: >-
            The method used to enter the card's details for the payment. The
            method can be

            `KEYED`, `SWIPED`, `EMV`, `ON_FILE`, or `CONTACTLESS`.
          maxLength: 50
          nullable: true
        cvv_status:
          type: string
          description: >-
            The status code returned from the Card Verification Value (CVV)
            check. The code can be

            `CVV_ACCEPTED`, `CVV_REJECTED`, or `CVV_NOT_CHECKED`.
          maxLength: 50
          nullable: true
        avs_status:
          type: string
          description: >-
            The status code returned from the Address Verification System (AVS)
            check. The code can be

            `AVS_ACCEPTED`, `AVS_REJECTED`, or `AVS_NOT_CHECKED`.
          maxLength: 50
          nullable: true
        auth_result_code:
          type: string
          description: >-
            The status code returned by the card issuer that describes the
            payment's

            authorization status.
          maxLength: 10
          nullable: true
        application_identifier:
          type: string
          description: >-
            For EMV payments, the application ID identifies the EMV application
            used for the payment.
          maxLength: 32
          nullable: true
        application_name:
          type: string
          description: >-
            For EMV payments, the human-readable name of the EMV application
            used for the payment.
          maxLength: 16
          nullable: true
        application_cryptogram:
          type: string
          description: For EMV payments, the cryptogram generated for the payment.
          maxLength: 16
          nullable: true
        verification_method:
          type: string
          description: >-
            For EMV payments, the method used to verify the cardholder's
            identity. The method can be

            `PIN`, `SIGNATURE`, `PIN_AND_SIGNATURE`, `ON_DEVICE`, or `NONE`.
          maxLength: 50
          nullable: true
        verification_results:
          type: string
          description: >-
            For EMV payments, the results of the cardholder verification. The
            result can be

            `SUCCESS`, `FAILURE`, or `UNKNOWN`.
          maxLength: 50
          nullable: true
        statement_description:
          type: string
          description: >-
            The statement description sent to the card networks.


            Note: The actual statement description varies and is likely to be
            truncated and appended with

            additional information on a per issuer basis.
          maxLength: 50
          nullable: true
        device_details:
          $ref: '#/components/schemas/DeviceDetails'
          description: |-
            __Deprecated__: Use `Payment.device_details` instead.

            Details about the device that took the payment.
          x-release-status: DEPRECATED
          nullable: true
        card_payment_timeline:
          $ref: '#/components/schemas/CardPaymentTimeline'
          description: The timeline for card payments.
          nullable: true
        refund_requires_card_presence:
          type: boolean
          description: |-
            Whether the card must be physically present for the payment to
            be refunded.  If set to `true`, the card must be present.
          x-release-status: BETA
          nullable: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
          nullable: true
    CardPaymentTimeline:
      type: object
      description: The timeline for card payments.
      x-release-status: PUBLIC
      properties:
        authorized_at:
          type: string
          description: The timestamp when the payment was authorized, in RFC 3339 format.
          nullable: true
        captured_at:
          type: string
          description: The timestamp when the payment was captured, in RFC 3339 format.
          nullable: true
        voided_at:
          type: string
          description: The timestamp when the payment was voided, in RFC 3339 format.
          nullable: true
    CardPrepaidType:
      type: string
      enum:
        - UNKNOWN_PREPAID_TYPE
        - NOT_PREPAID
        - PREPAID
      x-enum-elements:
        - name: UNKNOWN_PREPAID_TYPE
          description: ''
        - name: NOT_PREPAID
          description: ''
        - name: PREPAID
          description: ''
      description: Indicates a card's prepaid type, such as `NOT_PREPAID` or `PREPAID`.
      x-release-status: PUBLIC
    CardType:
      type: string
      enum:
        - UNKNOWN_CARD_TYPE
        - CREDIT
        - DEBIT
      x-enum-elements:
        - name: UNKNOWN_CARD_TYPE
          description: ''
        - name: CREDIT
          description: ''
        - name: DEBIT
          description: ''
      description: Indicates a card's type, such as `CREDIT` or `DEBIT`.
      x-release-status: PUBLIC
    CashAppDetails:
      type: object
      description: >-
        Additional details about `WALLET` type payments with the `brand` of
        `CASH_APP`.
      x-release-status: PUBLIC
      properties:
        buyer_full_name:
          type: string
          description: The name of the Cash App account holder.
          maxLength: 255
          nullable: true
        buyer_country_code:
          type: string
          description: >-
            The country of the Cash App account holder, in ISO 3166-1-alpha-2
            format.


            For possible values, see [Country](entity:Country).
          minLength: 2
          maxLength: 2
          nullable: true
        buyer_cashtag:
          type: string
          description: $Cashtag of the Cash App account holder.
          minLength: 1
          maxLength: 21
          readOnly: true
    CashDrawerDevice:
      type: object
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: The device Square-issued ID
        name:
          type: string
          description: The device merchant-specified name.
          nullable: true
    CashDrawerEventType:
      type: string
      enum:
        - NO_SALE
        - CASH_TENDER_PAYMENT
        - OTHER_TENDER_PAYMENT
        - CASH_TENDER_CANCELLED_PAYMENT
        - OTHER_TENDER_CANCELLED_PAYMENT
        - CASH_TENDER_REFUND
        - OTHER_TENDER_REFUND
        - PAID_IN
        - PAID_OUT
      x-enum-elements:
        - name: NO_SALE
          description: |-
            Triggered when a no sale occurs on a cash drawer.
            A CashDrawerEvent of this type must have a zero money amount.
        - name: CASH_TENDER_PAYMENT
          description: |-
            Triggered when a cash tender payment occurs on a cash drawer.
            A CashDrawerEvent of this type can must not have a negative amount.
        - name: OTHER_TENDER_PAYMENT
          description: |-
            Triggered when a check, gift card, or other non-cash payment occurs
            on a cash drawer.
            A CashDrawerEvent of this type must have a zero money amount.
        - name: CASH_TENDER_CANCELLED_PAYMENT
          description: >-
            Triggered when a split tender bill is cancelled after cash has been

            tendered.

            A CASH_TENDER_CANCELLED_PAYMENT should have a corresponding
            CASH_TENDER_PAYMENT.

            A CashDrawerEvent of this type must not have a negative amount.
        - name: OTHER_TENDER_CANCELLED_PAYMENT
          description: >-
            Triggered when a split tender bill is cancelled after a non-cash
            tender

            has been tendered. An OTHER_TENDER_CANCELLED_PAYMENT should have a
            corresponding

            OTHER_TENDER_PAYMENT. A CashDrawerEvent of this type must have a
            zero money

            amount.
        - name: CASH_TENDER_REFUND
          description: |-
            Triggered when a cash tender refund occurs.
            A CashDrawerEvent of this type must not have a negative amount.
        - name: OTHER_TENDER_REFUND
          description: |-
            Triggered when an other tender refund occurs.
            A CashDrawerEvent of this type must have a zero money amount.
        - name: PAID_IN
          description: >-
            Triggered when money unrelated to a payment is added to the cash
            drawer.

            For example, an employee adds coins to the drawer.

            A CashDrawerEvent of this type must not have a negative amount.
        - name: PAID_OUT
          description: >-
            Triggered when money is removed from the drawer for other reasons

            than making change.

            For example, an employee pays a delivery person with cash from the
            cash drawer.

            A CashDrawerEvent of this type must not have a negative amount.
      description: |-
        The types of events on a CashDrawerShift.
        Each event type represents an employee action on the actual cash drawer
        represented by a CashDrawerShift.
      x-release-status: PUBLIC
    CashDrawerShift:
      type: object
      description: >-
        This model gives the details of a cash drawer shift.

        The cash_payment_money, cash_refund_money, cash_paid_in_money,

        and cash_paid_out_money fields are all computed by summing their
        respective

        event types.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: The shift unique ID.
        state:
          $ref: '#/components/schemas/CashDrawerShiftState'
          description: >-
            The shift current state.

            See [CashDrawerShiftState](#type-cashdrawershiftstate) for possible
            values
          nullable: true
        opened_at:
          type: string
          description: The time when the shift began, in ISO 8601 format.
          nullable: true
        ended_at:
          type: string
          description: The time when the shift ended, in ISO 8601 format.
          nullable: true
        closed_at:
          type: string
          description: The time when the shift was closed, in ISO 8601 format.
          nullable: true
        description:
          type: string
          description: The free-form text description of a cash drawer by an employee.
          nullable: true
        opened_cash_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The amount of money in the cash drawer at the start of the shift.
            The amount must be greater than or equal to zero.
          nullable: true
        cash_payment_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money added to the cash drawer from cash payments.

            This is computed by summing all events with the types
            CASH_TENDER_PAYMENT and

            CASH_TENDER_CANCELED_PAYMENT. The amount is always greater than or
            equal to

            zero.
          nullable: true
        cash_refunds_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money removed from the cash drawer from cash refunds.

            It is computed by summing the events of type CASH_TENDER_REFUND. The
            amount

            is always greater than or equal to zero.
          nullable: true
        cash_paid_in_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money added to the cash drawer for reasons other than
            cash

            payments. It is computed by summing the events of type PAID_IN. The
            amount is

            always greater than or equal to zero.
          nullable: true
        cash_paid_out_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money removed from the cash drawer for reasons other
            than

            cash refunds. It is computed by summing the events of type PAID_OUT.
            The amount

            is always greater than or equal to zero.
          nullable: true
        expected_cash_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money that should be in the cash drawer at the end of
            the

            shift, based on the shift's other money amounts.

            This can be negative if employees have not correctly recorded all
            the events

            on the cash drawer.

            cash_paid_out_money is a summation of amounts from
            cash_payment_money (zero

            or positive), cash_refunds_money (zero or negative),
            cash_paid_in_money (zero

            or positive), and cash_paid_out_money (zero or negative) event
            types.
          nullable: true
        closed_cash_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The amount of money found in the cash drawer at the end of the shift
            by an auditing employee. The amount should be positive.
          nullable: true
        device:
          $ref: '#/components/schemas/CashDrawerDevice'
          description: >-
            The device running Square Point of Sale that was connected to the
            cash drawer.
          nullable: true
        created_at:
          type: string
          description: The shift start time in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: The shift updated at time in RFC 3339 format.
          readOnly: true
        location_id:
          type: string
          description: The ID of the location the cash drawer shift belongs to.
          readOnly: true
        team_member_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of all team members that were logged into Square Point of
            Sale at any

            point while the cash drawer shift was open.
          readOnly: true
        opening_team_member_id:
          type: string
          description: The ID of the team member that started the cash drawer shift.
          readOnly: true
        ending_team_member_id:
          type: string
          description: The ID of the team member that ended the cash drawer shift.
          readOnly: true
        closing_team_member_id:
          type: string
          description: >-
            The ID of the team member that closed the cash drawer shift by
            auditing

            the cash drawer contents.
          readOnly: true
    CashDrawerShiftEvent:
      type: object
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: The unique ID of the event.
        event_type:
          $ref: '#/components/schemas/CashDrawerEventType'
          description: >-
            The type of cash drawer shift event.

            See [CashDrawerEventType](#type-cashdrawereventtype) for possible
            values
          nullable: true
        event_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money that was added to or removed from the cash
            drawer

            in the event. The amount can be positive (for added money)

            or zero (for other tender type payments). The addition or removal of
            money can be determined by

            by the event type.
          nullable: true
        created_at:
          type: string
          description: The event time in RFC 3339 format.
          readOnly: true
        description:
          type: string
          description: |-
            An optional description of the event, entered by the employee that
            created the event.
          nullable: true
        team_member_id:
          type: string
          description: The ID of the team member that created the event.
          readOnly: true
    CashDrawerShiftState:
      type: string
      enum:
        - OPEN
        - ENDED
        - CLOSED
      x-enum-elements:
        - name: OPEN
          description: An open cash drawer shift.
        - name: ENDED
          description: >-
            A cash drawer shift that is ended but has not yet had an employee
            content audit.
        - name: CLOSED
          description: |-
            An ended cash drawer shift that is closed with a completed employee
            content audit and recorded result.
      description: The current state of a cash drawer shift.
      x-release-status: PUBLIC
    CashDrawerShiftSummary:
      type: object
      description: >-
        The summary of a closed cash drawer shift.

        This model contains only the money counted to start a cash drawer shift,
        counted

        at the end of the shift, and the amount that should be in the drawer at
        shift

        end based on summing all cash drawer shift events.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: The shift unique ID.
        state:
          $ref: '#/components/schemas/CashDrawerShiftState'
          description: >-
            The shift current state.

            See [CashDrawerShiftState](#type-cashdrawershiftstate) for possible
            values
          nullable: true
        opened_at:
          type: string
          description: The shift start time in ISO 8601 format.
          nullable: true
        ended_at:
          type: string
          description: The shift end time in ISO 8601 format.
          nullable: true
        closed_at:
          type: string
          description: The shift close time in ISO 8601 format.
          nullable: true
        description:
          type: string
          description: An employee free-text description of a cash drawer shift.
          nullable: true
        opened_cash_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money in the cash drawer at the start of the shift.
            This

            must be a positive amount.
          nullable: true
        expected_cash_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money that should be in the cash drawer at the end of
            the

            shift, based on the cash drawer events on the shift.

            The amount is correct if all shift employees accurately recorded
            their

            cash drawer shift events. Unrecorded events and events with the
            wrong amount

            result in an incorrect expected_cash_money amount that can be
            negative.
          nullable: true
        closed_cash_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money found in the cash drawer at the end of the shift
            by

            an auditing employee. The amount must be greater than or equal to
            zero.
          nullable: true
        created_at:
          type: string
          description: The shift start time in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: The shift updated at time in RFC 3339 format.
          readOnly: true
        location_id:
          type: string
          description: The ID of the location the cash drawer shift belongs to.
          readOnly: true
    CashPaymentDetails:
      type: object
      description: >-
        Stores details about a cash payment. Contains only non-confidential
        information. For more information, see 

        [Take Cash
        Payments](https://developer.squareup.com/docs/payments-api/take-payments/cash-payments).
      x-release-status: PUBLIC
      required:
        - buyer_supplied_money
      properties:
        buyer_supplied_money:
          $ref: '#/components/schemas/Money'
          description: The amount and currency of the money supplied by the buyer.
        change_back_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The amount of change due back to the buyer. 
            This read-only field is calculated
            from the `amount_money` and `buyer_supplied_money` fields.
          nullable: true
    CatalogAvailabilityPeriod:
      type: object
      description: Represents a time period of availability.
      x-release-status: BETA
      properties:
        start_local_time:
          type: string
          description: >-
            The start time of an availability period, specified in local time
            using partial-time

            RFC 3339 format. For example, `8:30:00` for a period starting at
            8:30 in the morning.

            Note that the seconds value is always :00, but it is appended for
            conformance to the RFC.
          nullable: true
        end_local_time:
          type: string
          description: >-
            The end time of an availability period, specified in local time
            using partial-time

            RFC 3339 format. For example, `21:00:00` for a period ending at 9:00
            in the evening.

            Note that the seconds value is always :00, but it is appended for
            conformance to the RFC.
          nullable: true
        day_of_week:
          $ref: '#/components/schemas/DayOfWeek'
          description: |-
            The day of the week for this availability period.
            See [DayOfWeek](#type-dayofweek) for possible values
          nullable: true
    CatalogCategory:
      type: object
      description: A category to which a `CatalogItem` instance belongs.
      x-release-status: PUBLIC
      properties:
        name:
          type: string
          description: >-
            The category name. This is a searchable attribute for use in
            applicable query filters, and its value length is of Unicode code
            points.
          maxLength: 255
          nullable: true
        image_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of images associated with this `CatalogCategory` instance.

            Currently these images are not displayed by Square, but are free to
            be displayed in 3rd party applications.
          nullable: true
        category_type:
          $ref: '#/components/schemas/CatalogCategoryType'
          description: >-
            The type of the category.

            See [CatalogCategoryType](#type-catalogcategorytype) for possible
            values
          nullable: true
        parent_category:
          $ref: '#/components/schemas/CatalogObjectCategory'
          description: The ID of the parent category of this category instance.
          nullable: true
        is_top_level:
          type: boolean
          description: >-
            Indicates whether a category is a top level category, which does not
            have any parent_category.
          nullable: true
        channels:
          type: array
          items:
            type: string
          description: >-
            A list of IDs representing channels, such as a Square Online site,
            where the category can be made visible.
          nullable: true
        availability_period_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of the `CatalogAvailabilityPeriod` objects associated with
            the category.
          nullable: true
        online_visibility:
          type: boolean
          description: >-
            Indicates whether the category is visible (`true`) or hidden
            (`false`) on all of the seller's Square Online sites.
          nullable: true
        root_category:
          type: string
          description: The top-level category in a category hierarchy.
          readOnly: true
        ecom_seo_data:
          $ref: '#/components/schemas/CatalogEcomSeoData'
          description: The SEO data for a seller's Square Online store.
          nullable: true
        path_to_root:
          type: array
          items:
            $ref: '#/components/schemas/CategoryPathToRootNode'
          description: >-
            The path from the category to its root category. The first node of
            the path is the parent of the category

            and the last is the root category. The path is empty if the category
            is a root category.
          nullable: true
      example:
        object:
          category_data:
            name: Beverages
          id: '#Beverages'
          present_at_all_locations: true
          type: CATEGORY
    CatalogCategoryType:
      type: string
      enum:
        - REGULAR_CATEGORY
        - MENU_CATEGORY
        - KITCHEN_CATEGORY
      x-enum-elements:
        - name: REGULAR_CATEGORY
          description: The regular category.
        - name: MENU_CATEGORY
          description: The menu category.
        - name: KITCHEN_CATEGORY
          description: >-
            Kitchen categories are used by KDS (Kitchen Display System) to route
            items to specific clients
      description: Indicates the type of a category.
      x-release-status: PUBLIC
    CatalogCustomAttributeDefinition:
      type: object
      description: >-
        Contains information defining a custom attribute. Custom attributes are

        intended to store additional information about a catalog object or to
        associate a

        catalog object with an entity in another system. Do not use custom
        attributes

        to store any sensitive information (personally identifiable information,
        card details, etc.).

        [Read more about custom
        attributes](https://developer.squareup.com/docs/catalog-api/add-custom-attributes)
      x-release-status: PUBLIC
      required:
        - type
        - name
        - allowed_object_types
      properties:
        type:
          $ref: '#/components/schemas/CatalogCustomAttributeDefinitionType'
          description: >-
            The type of this custom attribute. Cannot be modified after
            creation.

            Required.

            See
            [CatalogCustomAttributeDefinitionType](#type-catalogcustomattributedefinitiontype)
            for possible values
        name:
          type: string
          description: >2-
             The name of this definition for API and seller-facing UI purposes.
            The name must be unique within the (merchant, application) pair.
            Required.

            May not be empty and may not exceed 255 characters. Can be modified
            after creation.
          minLength: 1
          maxLength: 255
        description:
          type: string
          description: >-
            Seller-oriented description of the meaning of this Custom Attribute,

            any constraints that the seller should observe, etc. May be
            displayed as a tooltip in Square UIs.
          maxLength: 255
          nullable: true
        source_application:
          $ref: '#/components/schemas/SourceApplication'
          description: |-
            __Read only.__ Contains information about the application that
            created this custom attribute definition.
          nullable: true
        allowed_object_types:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObjectType'
          description: >-
            The set of `CatalogObject` types that this custom atttribute may be
            applied to.

            Currently, only `ITEM`, `ITEM_VARIATION`, `MODIFIER`,
            `MODIFIER_LIST`, and `CATEGORY` are allowed. At least one type must
            be included.

            See [CatalogObjectType](#type-catalogobjecttype) for possible values
        seller_visibility:
          $ref: >-
            #/components/schemas/CatalogCustomAttributeDefinitionSellerVisibility
          description: >-
            The visibility of a custom attribute in seller-facing UIs (including
            Square Point

            of Sale applications and Square Dashboard). May be modified.

            See
            [CatalogCustomAttributeDefinitionSellerVisibility](#type-catalogcustomattributedefinitionsellervisibility)
            for possible values
          nullable: true
        app_visibility:
          $ref: '#/components/schemas/CatalogCustomAttributeDefinitionAppVisibility'
          description: >-
            The visibility of a custom attribute to applications other than the
            application

            that created the attribute.

            See
            [CatalogCustomAttributeDefinitionAppVisibility](#type-catalogcustomattributedefinitionappvisibility)
            for possible values
          nullable: true
        string_config:
          $ref: '#/components/schemas/CatalogCustomAttributeDefinitionStringConfig'
          description: Optionally, populated when `type` = `STRING`, unset otherwise.
          nullable: true
        number_config:
          $ref: '#/components/schemas/CatalogCustomAttributeDefinitionNumberConfig'
          description: Optionally, populated when `type` = `NUMBER`, unset otherwise.
          nullable: true
        selection_config:
          $ref: '#/components/schemas/CatalogCustomAttributeDefinitionSelectionConfig'
          description: Populated when `type` is set to `SELECTION`, unset otherwise.
          nullable: true
        custom_attribute_usage_count:
          type: integer
          description: >-
            The number of custom attributes that reference this

            custom attribute definition. Set by the server in response to a
            ListCatalog

            request with `include_counts` set to `true`.  If the actual count is
            greater

            than 100, `custom_attribute_usage_count` will be set to `100`.
          readOnly: true
        key:
          type: string
          description: >-
            The name of the desired custom attribute key that can be used to
            access

            the custom attribute value on catalog objects. Cannot be modified
            after the

            custom attribute definition has been created.

            Must be between 1 and 60 characters, and may only contain the
            characters `[a-zA-Z0-9_-]`.
          minLength: 1
          maxLength: 60
          pattern: ^[a-zA-Z0-9_-]*$
          nullable: true
    CatalogCustomAttributeDefinitionAppVisibility:
      type: string
      enum:
        - APP_VISIBILITY_HIDDEN
        - APP_VISIBILITY_READ_ONLY
        - APP_VISIBILITY_READ_WRITE_VALUES
      x-enum-elements:
        - name: APP_VISIBILITY_HIDDEN
          description: Other applications cannot read this custom attribute.
        - name: APP_VISIBILITY_READ_ONLY
          description: |-
            Other applications can read this custom attribute definition and
            values.
        - name: APP_VISIBILITY_READ_WRITE_VALUES
          description: >-
            Other applications can read and write custom attribute values on
            objects.

            They can read but cannot edit the custom attribute definition.
      description: >-
        Defines the visibility of a custom attribute to applications other than
        their

        creating application.
      x-release-status: PUBLIC
    CatalogCustomAttributeDefinitionNumberConfig:
      type: object
      x-release-status: PUBLIC
      properties:
        precision:
          type: integer
          description: >-
            An integer between 0 and 5 that represents the maximum number of

            positions allowed after the decimal in number custom attribute
            values

            For example:


            - if the precision is 0, the quantity can be 1, 2, 3, etc.

            - if the precision is 1, the quantity can be 0.1, 0.2, etc.

            - if the precision is 2, the quantity can be 0.01, 0.12, etc.


            Default: 5
          maximum: 5
          nullable: true
    CatalogCustomAttributeDefinitionSelectionConfig:
      type: object
      description: >-
        Configuration associated with `SELECTION`-type custom attribute
        definitions.
      x-release-status: PUBLIC
      properties:
        max_allowed_selections:
          type: integer
          description: >-
            The maximum number of selections that can be set. The maximum value
            for this

            attribute is 100. The default value is 1. The value can be modified,
            but changing the value will not

            affect existing custom attribute values on objects. Clients need to

            handle custom attributes with more selected values than allowed by
            this limit.
          maximum: 100
          nullable: true
        allowed_selections:
          type: array
          items:
            $ref: >-
              #/components/schemas/CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection
          description: >-
            The set of valid `CatalogCustomAttributeSelections`. Up to a maximum
            of 100

            selections can be defined. Can be modified.
          nullable: true
    CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection:
      type: object
      description: A named selection for this `SELECTION`-type custom attribute definition.
      x-release-status: PUBLIC
      required:
        - name
      properties:
        uid:
          type: string
          description: Unique ID set by Square.
          nullable: true
        name:
          type: string
          description: Selection name, unique within `allowed_selections`.
          minLength: 1
          maxLength: 255
    CatalogCustomAttributeDefinitionSellerVisibility:
      type: string
      enum:
        - SELLER_VISIBILITY_HIDDEN
        - SELLER_VISIBILITY_READ_WRITE_VALUES
      x-enum-elements:
        - name: SELLER_VISIBILITY_HIDDEN
          description: |-
            Sellers cannot read this custom attribute in Square client
            applications or Square APIs.
        - name: SELLER_VISIBILITY_READ_WRITE_VALUES
          description: >-
            Sellers can read and write this custom attribute value in catalog
            objects,

            but cannot edit the custom attribute definition.
      description: >-
        Defines the visibility of a custom attribute to sellers in Square

        client applications, Square APIs or in Square UIs (including Square
        Point

        of Sale applications and Square Dashboard).
      x-release-status: PUBLIC
    CatalogCustomAttributeDefinitionStringConfig:
      type: object
      description: >-
        Configuration associated with Custom Attribute Definitions of type
        `STRING`.
      x-release-status: PUBLIC
      properties:
        enforce_uniqueness:
          type: boolean
          description: >-
            If true, each Custom Attribute instance associated with this Custom
            Attribute

            Definition must have a unique value within the seller's catalog. For

            example, this may be used for a value like a SKU that should not be

            duplicated within a seller's catalog. May not be modified after the

            definition has been created.
          nullable: true
    CatalogCustomAttributeDefinitionType:
      type: string
      enum:
        - STRING
        - BOOLEAN
        - NUMBER
        - SELECTION
      x-enum-elements:
        - name: STRING
          description: A free-form string containing up to 255 characters.
        - name: BOOLEAN
          description: A `true` or `false` value.
        - name: NUMBER
          description: >-
            A decimal string representation of a number. Can support up to 5
            digits after the decimal point.
        - name: SELECTION
          description: One or more choices from `allowed_selections`.
      description: Defines the possible types for a custom attribute.
      x-release-status: PUBLIC
    CatalogCustomAttributeValue:
      type: object
      description: >-
        An instance of a custom attribute. Custom attributes can be defined and

        added to `ITEM` and `ITEM_VARIATION` type catalog objects.

        [Read more about custom
        attributes](https://developer.squareup.com/docs/catalog-api/add-custom-attributes).
      x-release-status: PUBLIC
      properties:
        name:
          type: string
          description: The name of the custom attribute.
          nullable: true
        string_value:
          type: string
          description: >-
            The string value of the custom attribute.  Populated if `type` =
            `STRING`.
          nullable: true
        custom_attribute_definition_id:
          type: string
          description: >-
            The id of the
            [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition)
            this value belongs to.
          readOnly: true
        type:
          $ref: '#/components/schemas/CatalogCustomAttributeDefinitionType'
          description: >-
            A copy of type from the associated
            `CatalogCustomAttributeDefinition`.

            See
            [CatalogCustomAttributeDefinitionType](#type-catalogcustomattributedefinitiontype)
            for possible values
          readOnly: true
        number_value:
          type: string
          description: >-
            Populated if `type` = `NUMBER`. Contains a string

            representation of a decimal number, using a `.` as the decimal
            separator.
          nullable: true
        boolean_value:
          type: boolean
          description: A `true` or `false` value. Populated if `type` = `BOOLEAN`.
          nullable: true
        selection_uid_values:
          type: array
          items:
            type: string
          description: >-
            One or more choices from `allowed_selections`. Populated if `type` =
            `SELECTION`.
          nullable: true
        key:
          type: string
          description: >-
            If the associated `CatalogCustomAttributeDefinition` object is
            defined by another application, this key is prefixed by the defining
            application ID.

            For example, if the CatalogCustomAttributeDefinition has a key
            attribute of "cocoa_brand" and the defining application ID is
            "abcd1234", this key is "abcd1234:cocoa_brand"

            when the application making the request is different from the
            application defining the custom attribute definition. Otherwise, the
            key is simply "cocoa_brand".
          readOnly: true
    CatalogDiscount:
      type: object
      description: A discount applicable to items.
      x-release-status: PUBLIC
      properties:
        name:
          type: string
          description: >-
            The discount name. This is a searchable attribute for use in
            applicable query filters, and its value length is of Unicode code
            points.
          maxLength: 255
          nullable: true
        discount_type:
          $ref: '#/components/schemas/CatalogDiscountType'
          description: >-
            Indicates whether the discount is a fixed amount or percentage, or
            entered at the time of sale.

            See [CatalogDiscountType](#type-catalogdiscounttype) for possible
            values
          nullable: true
        percentage:
          type: string
          description: >-
            The percentage of the discount as a string representation of a
            decimal number, using a `.` as the decimal

            separator and without a `%` sign. A value of `7.5` corresponds to
            `7.5%`. Specify a percentage of `0` if `discount_type`

            is `VARIABLE_PERCENTAGE`.


            Do not use this field for amount-based or variable discounts.
          nullable: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of the discount. Specify an amount of `0` if
            `discount_type` is `VARIABLE_AMOUNT`.


            Do not use this field for percentage-based or variable discounts.
          nullable: true
        pin_required:
          type: boolean
          description: >-
            Indicates whether a mobile staff member needs to enter their PIN to
            apply the

            discount to a payment in the Square Point of Sale app.
          nullable: true
        label_color:
          type: string
          description: >-
            The color of the discount display label in the Square Point of Sale
            app. This must be a valid hex color code.
          nullable: true
        modify_tax_basis:
          $ref: '#/components/schemas/CatalogDiscountModifyTaxBasis'
          description: >-
            Indicates whether this discount should reduce the price used to
            calculate tax.


            Most discounts should use `MODIFY_TAX_BASIS`. However, in some
            circumstances taxes must

            be calculated based on an item's price, ignoring a particular
            discount. For example,

            in many US jurisdictions, a manufacturer coupon or instant rebate
            reduces the price a

            customer pays but does not reduce the sale price used to calculate
            how much sales tax is

            due. In this case, the discount representing that manufacturer
            coupon should have

            `DO_NOT_MODIFY_TAX_BASIS` for this field.


            If you are unsure whether you need to use this field, consult your
            tax professional.

            See
            [CatalogDiscountModifyTaxBasis](#type-catalogdiscountmodifytaxbasis)
            for possible values
          nullable: true
        maximum_amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            For a percentage discount, the maximum absolute value of the
            discount. For example, if a

            50% discount has a `maximum_amount_money` of $20, a $100 purchase
            will yield a $20 discount,

            not a $50 discount.
          nullable: true
      example:
        object:
          discount_data:
            discount_type: FIXED_PERCENTAGE
            label_color: red
            name: Welcome to the Dark(Roast) Side!
            percentage: '5.4'
            pin_required: false
          id: '#Maythe4th'
          present_at_all_locations: true
          type: DISCOUNT
    CatalogDiscountModifyTaxBasis:
      type: string
      enum:
        - MODIFY_TAX_BASIS
        - DO_NOT_MODIFY_TAX_BASIS
      x-enum-elements:
        - name: MODIFY_TAX_BASIS
          description: Application of the discount will modify the tax basis.
        - name: DO_NOT_MODIFY_TAX_BASIS
          description: Application of the discount will not modify the tax basis.
      x-release-status: PUBLIC
    CatalogDiscountType:
      type: string
      enum:
        - FIXED_PERCENTAGE
        - FIXED_AMOUNT
        - VARIABLE_PERCENTAGE
        - VARIABLE_AMOUNT
      x-enum-elements:
        - name: FIXED_PERCENTAGE
          description: >-
            Apply the discount as a fixed percentage (e.g., 5%) off the item
            price.
        - name: FIXED_AMOUNT
          description: >-
            Apply the discount as a fixed amount (e.g., $1.00) off the item
            price.
        - name: VARIABLE_PERCENTAGE
          description: >-
            Apply the discount as a variable percentage off the item price. The
            percentage will be specified at the time of sale.
        - name: VARIABLE_AMOUNT
          description: >-
            Apply the discount as a variable amount off the item price. The
            amount will be specified at the time of sale.
      description: How to apply a CatalogDiscount to a CatalogItem.
      x-release-status: PUBLIC
    CatalogEcomSeoData:
      type: object
      description: SEO data for for a seller's Square Online store.
      x-release-status: PUBLIC
      properties:
        page_title:
          type: string
          description: The SEO title used for the Square Online store.
          nullable: true
        page_description:
          type: string
          description: The SEO description used for the Square Online store.
          nullable: true
        permalink:
          type: string
          description: The SEO permalink used for the Square Online store.
          nullable: true
    CatalogIdMapping:
      type: object
      description: >-
        A mapping between a temporary client-supplied ID and a permanent
        server-generated ID.


        When calling
        [UpsertCatalogObject](api-endpoint:Catalog-UpsertCatalogObject) or

        [BatchUpsertCatalogObjects](api-endpoint:Catalog-BatchUpsertCatalogObjects)
        to

        create a [CatalogObject](entity:CatalogObject) instance, you can supply

        a temporary ID for the to-be-created object, especially when the object
        is to be referenced

        elsewhere in the same request body. This temporary ID can be any string
        unique within

        the call, but must be prefixed by "#".


        After the request is submitted and the object created, a permanent
        server-generated ID is assigned

        to the new object. The permanent ID is unique across the Square catalog.
      x-release-status: PUBLIC
      properties:
        client_object_id:
          type: string
          description: >-
            The client-supplied temporary `#`-prefixed ID for a new
            `CatalogObject`.
          nullable: true
        object_id:
          type: string
          description: The permanent ID for the CatalogObject created by the server.
          nullable: true
    CatalogImage:
      type: object
      description: >-
        An image file to use in Square catalogs. It can be associated with

        `CatalogItem`, `CatalogItemVariation`, `CatalogCategory`, and
        `CatalogModifierList` objects.

        Only the images on items and item variations are exposed in Dashboard.

        Only the first image on an item is displayed in Square Point of Sale
        (SPOS).

        Images on items and variations are displayed through Square Online
        Store.

        Images on other object types are for use by 3rd party application
        developers.
      x-release-status: PUBLIC
      properties:
        name:
          type: string
          description: >-
            The internal name to identify this image in calls to the Square API.

            This is a searchable attribute for use in applicable query filters

            using the
            [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects).

            It is not unique and should not be shown in a buyer facing context.
          nullable: true
        url:
          type: string
          description: >-
            The URL of this image, generated by Square after an image is
            uploaded

            using the
            [CreateCatalogImage](api-endpoint:Catalog-CreateCatalogImage)
            endpoint.

            To modify the image, use the UpdateCatalogImage endpoint. Do not
            change the URL field.
          nullable: true
        caption:
          type: string
          description: >-
            A caption that describes what is shown in the image. Displayed in
            the

            Square Online Store. This is a searchable attribute for use in
            applicable query filters

            using the
            [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects).
          nullable: true
        photo_studio_order_id:
          type: string
          description: >-
            The immutable order ID for this image object created by the Photo
            Studio service in Square Online Store.
          nullable: true
    CatalogInfoRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/Catalog/CatalogInfo/CatalogInfoRequest.csharp
        java: /sdk_samples/Catalog/CatalogInfo/CatalogInfoRequest.java
        javascript: /sdk_samples/Catalog/CatalogInfo/CatalogInfoRequest.javascript
        php: /sdk_samples/Catalog/CatalogInfo/CatalogInfoRequest.php
        python: /sdk_samples/Catalog/CatalogInfo/CatalogInfoRequest.python
        ruby: /sdk_samples/Catalog/CatalogInfo/CatalogInfoRequest.ruby
    CatalogInfoResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        limits:
          $ref: '#/components/schemas/CatalogInfoResponseLimits'
          description: Limits that apply to this API.
        standard_unit_description_group:
          $ref: '#/components/schemas/StandardUnitDescriptionGroup'
          description: Names and abbreviations for standard units.
      example:
        limits:
          batch_delete_max_object_ids: 200
          batch_retrieve_max_object_ids: 1000
          batch_upsert_max_objects_per_batch: 1000
          batch_upsert_max_total_objects: 10000
          search_max_page_limit: 1000
          update_item_modifier_lists_max_item_ids: 1000
          update_item_modifier_lists_max_modifier_lists_to_disable: 1000
          update_item_modifier_lists_max_modifier_lists_to_enable: 1000
          update_item_taxes_max_item_ids: 1000
          update_item_taxes_max_taxes_to_disable: 1000
          update_item_taxes_max_taxes_to_enable: 1000
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/Catalog/CatalogInfo/CatalogInfoResponse.csharp
        java: /sdk_samples/Catalog/CatalogInfo/CatalogInfoResponse.java
        javascript: /sdk_samples/Catalog/CatalogInfo/CatalogInfoResponse.javascript
        php: /sdk_samples/Catalog/CatalogInfo/CatalogInfoResponse.php
        python: /sdk_samples/Catalog/CatalogInfo/CatalogInfoResponse.python
        ruby: /sdk_samples/Catalog/CatalogInfo/CatalogInfoResponse.ruby
    CatalogInfoResponseLimits:
      type: object
      x-release-status: PUBLIC
      properties:
        batch_upsert_max_objects_per_batch:
          type: integer
          description: >-
            The maximum number of objects that may appear within a single batch
            in a

            `/v2/catalog/batch-upsert` request.
          nullable: true
        batch_upsert_max_total_objects:
          type: integer
          description: >-
            The maximum number of objects that may appear across all batches in
            a

            `/v2/catalog/batch-upsert` request.
          nullable: true
        batch_retrieve_max_object_ids:
          type: integer
          description: >-
            The maximum number of object IDs that may appear in a
            `/v2/catalog/batch-retrieve`

            request.
          nullable: true
        search_max_page_limit:
          type: integer
          description: |-
            The maximum number of results that may be returned in a page of a
            `/v2/catalog/search` response.
          nullable: true
        batch_delete_max_object_ids:
          type: integer
          description: |-
            The maximum number of object IDs that may be included in a single
            `/v2/catalog/batch-delete` request.
          nullable: true
        update_item_taxes_max_item_ids:
          type: integer
          description: |-
            The maximum number of item IDs that may be included in a single
            `/v2/catalog/update-item-taxes` request.
          nullable: true
        update_item_taxes_max_taxes_to_enable:
          type: integer
          description: >-
            The maximum number of tax IDs to be enabled that may be included in
            a single

            `/v2/catalog/update-item-taxes` request.
          nullable: true
        update_item_taxes_max_taxes_to_disable:
          type: integer
          description: >-
            The maximum number of tax IDs to be disabled that may be included in
            a single

            `/v2/catalog/update-item-taxes` request.
          nullable: true
        update_item_modifier_lists_max_item_ids:
          type: integer
          description: |-
            The maximum number of item IDs that may be included in a single
            `/v2/catalog/update-item-modifier-lists` request.
          nullable: true
        update_item_modifier_lists_max_modifier_lists_to_enable:
          type: integer
          description: >-
            The maximum number of modifier list IDs to be enabled that may be
            included in

            a single `/v2/catalog/update-item-modifier-lists` request.
          nullable: true
        update_item_modifier_lists_max_modifier_lists_to_disable:
          type: integer
          description: >-
            The maximum number of modifier list IDs to be disabled that may be
            included in

            a single `/v2/catalog/update-item-modifier-lists` request.
          nullable: true
    CatalogItem:
      type: object
      description: >-
        A [CatalogObject](entity:CatalogObject) instance of the `ITEM` type,
        also referred to as an item, in the catalog.
      x-release-status: PUBLIC
      properties:
        name:
          type: string
          description: >-
            The item's name. This is a searchable attribute for use in
            applicable query filters, its value must not be empty, and the
            length is of Unicode code points.
          maxLength: 512
          nullable: true
        description:
          type: string
          description: >-
            The item's description. This is a searchable attribute for use in
            applicable query filters, and its value length is of Unicode code
            points.


            Deprecated at 2022-07-20, this field is planned to retire in 6
            months. You should migrate to use `description_html` to set the
            description

            of the [CatalogItem](entity:CatalogItem) instance.  The
            `description` and `description_html` field values are kept in sync.
            If you try to

            set the both fields, the `description_html` text value overwrites
            the `description` value. Updates in one field are also reflected in
            the other,

            except for when you use an early version before Square API
            2022-07-20 and `description_html` is set to blank, setting the
            `description` value to null

            does not nullify `description_html`.
          maxLength: 4096
          x-release-status: DEPRECATED
          nullable: true
        abbreviation:
          type: string
          description: >-
            The text of the item's display label in the Square Point of Sale
            app. Only up to the first five characters of the string are used.

            This attribute is searchable, and its value length is of Unicode
            code points.
          maxLength: 24
          nullable: true
        label_color:
          type: string
          description: >-
            The color of the item's display label in the Square Point of Sale
            app. This must be a valid hex color code.
          nullable: true
        is_taxable:
          type: boolean
          description: >-
            Indicates whether the item is taxable (`true`) or non-taxable
            (`false`). Default is `true`.
          nullable: true
        category_id:
          type: string
          description: >-
            The ID of the item's category, if any. Deprecated since 2023-12-13.
            Use `CatalogItem.categories`, instead.
          x-release-status: DEPRECATED
          nullable: true
        tax_ids:
          type: array
          items:
            type: string
          description: >-
            A set of IDs indicating the taxes enabled for

            this item. When updating an item, any taxes listed here will be
            added to the item.

            Taxes may also be added to or deleted from an item using
            `UpdateItemTaxes`.
          nullable: true
        modifier_list_info:
          type: array
          items:
            $ref: '#/components/schemas/CatalogItemModifierListInfo'
          description: >-
            A set of `CatalogItemModifierListInfo` objects

            representing the modifier lists that apply to this item, along with
            the overrides and min

            and max limits that are specific to this item. Modifier lists

            may also be added to or deleted from an item using
            `UpdateItemModifierLists`.
          nullable: true
        variations:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: >-
            A list of [CatalogItemVariation](entity:CatalogItemVariation)
            objects for this item. An item must have

            at least one variation.
          nullable: true
        product_type:
          $ref: '#/components/schemas/CatalogItemProductType'
          description: >-
            The product type of the item. Once set, the `product_type` value
            cannot be modified.


            Items of the `LEGACY_SQUARE_ONLINE_SERVICE` and
            `LEGACY_SQUARE_ONLINE_MEMBERSHIP` product types can be updated

            but cannot be created using the API.

            See [CatalogItemProductType](#type-catalogitemproducttype) for
            possible values
          nullable: true
        skip_modifier_screen:
          type: boolean
          description: >-
            If `false`, the Square Point of Sale app will present the
            `CatalogItem`'s

            details screen immediately, allowing the merchant to choose
            `CatalogModifier`s

            before adding the item to the cart.  This is the default behavior.


            If `true`, the Square Point of Sale app will immediately add the
            item to the cart with the pre-selected

            modifiers, and merchants can edit modifiers by drilling down onto
            the item's details.


            Third-party clients are encouraged to implement similar behaviors.
          nullable: true
        item_options:
          type: array
          items:
            $ref: '#/components/schemas/CatalogItemOptionForItem'
          description: >-
            List of item options IDs for this item. Used to manage and group
            item

            variations in a specified order.


            Maximum: 6 item options.
          nullable: true
        image_ids:
          type: array
          items:
            type: string
          description: |-
            The IDs of images associated with this `CatalogItem` instance.
            These images will be shown to customers in Square Online Store.
            The first image will show up as the icon for this item in POS.
          x-release-status: BETA
          nullable: true
        sort_name:
          type: string
          description: >-
            A name to sort the item by. If this name is unspecified, namely, the
            `sort_name` field is absent, the regular `name` field is used for
            sorting.

            Its value must not be empty.


            It is currently supported for sellers of the Japanese locale only.
          x-release-status: BETA
          nullable: true
        categories:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObjectCategory'
          description: The list of categories.
          nullable: true
        description_html:
          type: string
          description: >-
            The item's description as expressed in valid HTML elements. The
            length of this field value, including those of HTML tags,

            is of Unicode points. With application query filters, the text
            values of the HTML elements and attributes are searchable. Invalid
            or

            unsupported HTML elements or attributes are ignored.


            Supported HTML elements include:

            - `a`: Link. Supports linking to website URLs, email address, and
            telephone numbers.

            - `b`, `strong`:  Bold text

            - `br`: Line break

            - `code`: Computer code

            - `div`: Section

            - `h1-h6`: Headings

            - `i`, `em`: Italics

            - `li`: List element

            - `ol`: Numbered list

            - `p`: Paragraph

            - `ul`: Bullet list

            - `u`: Underline



            Supported HTML attributes include:

            - `align`: Alignment of the text content

            - `href`: Link destination

            - `rel`: Relationship between link's target and source

            - `target`: Place to open the linked document
          maxLength: 65535
          nullable: true
        description_plaintext:
          type: string
          description: >-
            A server-generated plaintext version of the `description_html`
            field, without formatting tags.
          maxLength: 65535
          readOnly: true
        channels:
          type: array
          items:
            type: string
          description: >-
            A list of IDs representing channels, such as a Square Online site,
            where the item can be made visible or available.

            This field is read only and cannot be edited.
          nullable: true
        is_archived:
          type: boolean
          description: Indicates whether this item is archived (`true`) or not (`false`).
          nullable: true
        ecom_seo_data:
          $ref: '#/components/schemas/CatalogEcomSeoData'
          description: The SEO data for a seller's Square Online store.
          nullable: true
        food_and_beverage_details:
          $ref: '#/components/schemas/CatalogItemFoodAndBeverageDetails'
          description: The food and beverage-specific details for the `FOOD_AND_BEV` item.
          nullable: true
        reporting_category:
          $ref: '#/components/schemas/CatalogObjectCategory'
          description: The item's reporting category.
          nullable: true
      example:
        object:
          id: '#Cocoa'
          item_data:
            abbreviation: Ch
            description: Hot chocolate
            name: Cocoa
            visibility: PRIVATE
          present_at_all_locations: true
          type: ITEM
    CatalogItemFoodAndBeverageDetails:
      type: object
      description: The food and beverage-specific details of a `FOOD_AND_BEV` item.
      x-release-status: PUBLIC
      properties:
        calorie_count:
          type: integer
          description: >-
            The calorie count (in the unit of kcal) for the `FOOD_AND_BEV` type
            of items.
          nullable: true
        dietary_preferences:
          type: array
          items:
            $ref: >-
              #/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreference
          description: The dietary preferences for the `FOOD_AND_BEV` item.
          nullable: true
        ingredients:
          type: array
          items:
            $ref: '#/components/schemas/CatalogItemFoodAndBeverageDetailsIngredient'
          description: The ingredients for the `FOOD_AND_BEV` type item.
          nullable: true
    CatalogItemFoodAndBeverageDetailsDietaryPreference:
      type: object
      description: >-
        Dietary preferences that can be assigned to an `FOOD_AND_BEV` item and
        its ingredients.
      x-release-status: PUBLIC
      properties:
        type:
          $ref: >-
            #/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceType
          description: >-
            The dietary preference type. Supported values include `STANDARD` and
            `CUSTOM` as specified in
            `FoodAndBeverageDetails.DietaryPreferenceType`.

            See [DietaryPreferenceType](#type-dietarypreferencetype) for
            possible values
          nullable: true
        standard_name:
          $ref: >-
            #/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference
          description: >-
            The name of the dietary preference from a standard pre-defined list.
            This should be null if it's a custom dietary preference.

            See [StandardDietaryPreference](#type-standarddietarypreference) for
            possible values
          nullable: true
        custom_name:
          type: string
          description: >-
            The name of a user-defined custom dietary preference. This should be
            null if it's a standard dietary preference.
          nullable: true
    CatalogItemFoodAndBeverageDetailsDietaryPreferenceStandardDietaryPreference:
      type: string
      enum:
        - DAIRY_FREE
        - GLUTEN_FREE
        - HALAL
        - KOSHER
        - NUT_FREE
        - VEGAN
        - VEGETARIAN
      x-enum-elements:
        - name: DAIRY_FREE
          description: ''
        - name: GLUTEN_FREE
          description: ''
        - name: HALAL
          description: ''
        - name: KOSHER
          description: ''
        - name: NUT_FREE
          description: ''
        - name: VEGAN
          description: ''
        - name: VEGETARIAN
          description: ''
      description: >-
        Standard dietary preferences for food and beverage items that are
        recommended on item creation.
      x-release-status: PUBLIC
    CatalogItemFoodAndBeverageDetailsDietaryPreferenceType:
      type: string
      enum:
        - STANDARD
        - CUSTOM
      x-enum-elements:
        - name: STANDARD
          description: A standard value from a pre-determined list.
        - name: CUSTOM
          description: A user-defined custom value.
      description: >-
        The type of dietary preference for the `FOOD_AND_BEV` type of items and
        integredients.
      x-release-status: PUBLIC
    CatalogItemFoodAndBeverageDetailsIngredient:
      type: object
      description: Describes the ingredient used in a `FOOD_AND_BEV` item.
      x-release-status: PUBLIC
      properties:
        type:
          $ref: >-
            #/components/schemas/CatalogItemFoodAndBeverageDetailsDietaryPreferenceType
          description: >-
            The dietary preference type of the ingredient. Supported values
            include `STANDARD` and `CUSTOM` as specified in
            `FoodAndBeverageDetails.DietaryPreferenceType`.

            See [DietaryPreferenceType](#type-dietarypreferencetype) for
            possible values
          nullable: true
        standard_name:
          $ref: >-
            #/components/schemas/CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient
          description: >-
            The name of the ingredient from a standard pre-defined list. This
            should be null if it's a custom dietary preference.

            See [StandardIngredient](#type-standardingredient) for possible
            values
          nullable: true
        custom_name:
          type: string
          description: >-
            The name of a custom user-defined ingredient. This should be null if
            it's a standard dietary preference.
          nullable: true
    CatalogItemFoodAndBeverageDetailsIngredientStandardIngredient:
      type: string
      enum:
        - CELERY
        - CRUSTACEANS
        - EGGS
        - FISH
        - GLUTEN
        - LUPIN
        - MILK
        - MOLLUSCS
        - MUSTARD
        - PEANUTS
        - SESAME
        - SOY
        - SULPHITES
        - TREE_NUTS
      x-enum-elements:
        - name: CELERY
          description: ''
        - name: CRUSTACEANS
          description: ''
        - name: EGGS
          description: ''
        - name: FISH
          description: ''
        - name: GLUTEN
          description: ''
        - name: LUPIN
          description: ''
        - name: MILK
          description: ''
        - name: MOLLUSCS
          description: ''
        - name: MUSTARD
          description: ''
        - name: PEANUTS
          description: ''
        - name: SESAME
          description: ''
        - name: SOY
          description: ''
        - name: SULPHITES
          description: ''
        - name: TREE_NUTS
          description: ''
      description: >-
        Standard ingredients for food and beverage items that are recommended on
        item creation.
      x-release-status: PUBLIC
    CatalogItemModifierListInfo:
      type: object
      description: >-
        References a text-based modifier or a list of non text-based modifiers
        applied to a `CatalogItem` instance

        and specifies supported behaviors of the application.
      x-release-status: PUBLIC
      required:
        - modifier_list_id
      properties:
        modifier_list_id:
          type: string
          description: >-
            The ID of the `CatalogModifierList` controlled by this
            `CatalogModifierListInfo`.
          minLength: 1
        modifier_overrides:
          type: array
          items:
            $ref: '#/components/schemas/CatalogModifierOverride'
          description: >-
            A set of `CatalogModifierOverride` objects that override whether a
            given `CatalogModifier` is enabled by default.
          nullable: true
        min_selected_modifiers:
          type: integer
          description: >-
            If 0 or larger, the smallest number of `CatalogModifier`s that must
            be selected from this `CatalogModifierList`.

            The default value is `-1`.


            When  `CatalogModifierList.selection_type` is `MULTIPLE`,
            `CatalogModifierListInfo.min_selected_modifiers=-1` 

            and `CatalogModifierListInfo.max_selected_modifier=-1` means that
            from zero to the maximum number of modifiers of

            the `CatalogModifierList` can be selected from the
            `CatalogModifierList`. 


            When the `CatalogModifierList.selection_type` is `SINGLE`,
            `CatalogModifierListInfo.min_selected_modifiers=-1`

            and `CatalogModifierListInfo.max_selected_modifier=-1` means that
            exactly one modifier must be present in 

            and can be selected from the `CatalogModifierList`
          nullable: true
        max_selected_modifiers:
          type: integer
          description: >-
            If 0 or larger, the largest number of `CatalogModifier`s that can be
            selected from this `CatalogModifierList`.

            The default value is `-1`.


            When  `CatalogModifierList.selection_type` is `MULTIPLE`,
            `CatalogModifierListInfo.min_selected_modifiers=-1` 

            and `CatalogModifierListInfo.max_selected_modifier=-1` means that
            from zero to the maximum number of modifiers of

            the `CatalogModifierList` can be selected from the
            `CatalogModifierList`. 


            When the `CatalogModifierList.selection_type` is `SINGLE`,
            `CatalogModifierListInfo.min_selected_modifiers=-1`

            and `CatalogModifierListInfo.max_selected_modifier=-1` means that
            exactly one modifier must be present in 

            and can be selected from the `CatalogModifierList`
          nullable: true
        enabled:
          type: boolean
          description: >-
            If `true`, enable this `CatalogModifierList`. The default value is
            `true`.
          nullable: true
        ordinal:
          type: integer
          description: >-
            The position of this `CatalogItemModifierListInfo` object within the
            `modifier_list_info` list applied 

            to a `CatalogItem` instance.
          x-release-status: BETA
          nullable: true
    CatalogItemOption:
      type: object
      description: A group of variations for a `CatalogItem`.
      x-release-status: PUBLIC
      properties:
        name:
          type: string
          description: >-
            The item option's display name for the seller. Must be unique across

            all item options. This is a searchable attribute for use in
            applicable query filters.
          nullable: true
        display_name:
          type: string
          description: >-
            The item option's display name for the customer. This is a
            searchable attribute for use in applicable query filters.
          nullable: true
        description:
          type: string
          description: >-
            The item option's human-readable description. Displayed in the
            Square

            Point of Sale app for the seller and in the Online Store or on
            receipts for

            the buyer. This is a searchable attribute for use in applicable
            query filters.
          nullable: true
        show_colors:
          type: boolean
          description: If true, display colors for entries in `values` when present.
          nullable: true
        values:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: |-
            A list of CatalogObjects containing the
            `CatalogItemOptionValue`s for this item.
          nullable: true
    CatalogItemOptionForItem:
      type: object
      description: |2-
         An option that can be assigned to an item.
        For example, a t-shirt item may offer a color option or a size option.
      x-release-status: BETA
      properties:
        item_option_id:
          type: string
          description: >-
            The unique id of the item option, used to form the dimensions of the
            item option matrix in a specified order.
          nullable: true
    CatalogItemOptionValue:
      type: object
      description: |-
        An enumerated value that can link a
        `CatalogItemVariation` to an item option as one of
        its item option values.
      x-release-status: PUBLIC
      properties:
        item_option_id:
          type: string
          description: Unique ID of the associated item option.
          nullable: true
        name:
          type: string
          description: >-
            Name of this item option value. This is a searchable attribute for
            use in applicable query filters.
          nullable: true
        description:
          type: string
          description: >-
            A human-readable description for the option value. This is a
            searchable attribute for use in applicable query filters.
          nullable: true
        color:
          type: string
          description: >-
            The HTML-supported hex color for the item option (e.g.,
            "#ff8d4e85").

            Only displayed if `show_colors` is enabled on the parent
            `ItemOption`. When

            left unset, `color` defaults to white ("#ffffff") when `show_colors`
            is

            enabled on the parent `ItemOption`.
          nullable: true
        ordinal:
          type: integer
          description: >-
            Determines where this option value appears in a list of option
            values.
          nullable: true
    CatalogItemOptionValueForItemVariation:
      type: object
      description: >-
        A `CatalogItemOptionValue` links an item variation to an item option as

        an item option value. For example, a t-shirt item may offer a color
        option and

        a size option. An item option value would represent each variation of
        t-shirt:

        For example, "Color:Red, Size:Small" or "Color:Blue, Size:Medium".
      x-release-status: PUBLIC
      properties:
        item_option_id:
          type: string
          description: The unique id of an item option.
          nullable: true
        item_option_value_id:
          type: string
          description: The unique id of the selected value for the item option.
          nullable: true
    CatalogItemProductType:
      type: string
      enum:
        - REGULAR
        - GIFT_CARD
        - APPOINTMENTS_SERVICE
        - FOOD_AND_BEV
        - EVENT
        - DIGITAL
        - DONATION
        - LEGACY_SQUARE_ONLINE_SERVICE
        - LEGACY_SQUARE_ONLINE_MEMBERSHIP
      x-enum-elements:
        - name: REGULAR
          description: An ordinary item.
        - name: GIFT_CARD
          description: A Square gift card.
        - name: APPOINTMENTS_SERVICE
          description: A service that can be booked using the Square Appointments app.
        - name: FOOD_AND_BEV
          description: >-
            A food or beverage item that can be sold by restaurants and other
            food venues.
        - name: EVENT
          description: >-
            An event which tickets can be sold for, including location, address,
            and times.
        - name: DIGITAL
          description: A digital item like an ebook or song.
        - name: DONATION
          description: A donation which site visitors can send for any cause.
        - name: LEGACY_SQUARE_ONLINE_SERVICE
          description: >-
            A legacy Square Online service that is manually fulfilled. This
            corresponds to the `Other` item type displayed in the Square Seller
            Dashboard and Square POS apps.
        - name: LEGACY_SQUARE_ONLINE_MEMBERSHIP
          description: >-
            A legacy Square Online membership that is manually fulfilled. This
            corresponds to the `Membership` item type displayed in the Square
            Seller Dashboard and Square POS apps.
      description: >-
        The type of a CatalogItem. Connect V2 only allows the creation of
        `REGULAR` or `APPOINTMENTS_SERVICE` items.
      x-release-status: PUBLIC
    CatalogItemVariation:
      type: object
      description: >-
        An item variation, representing a product for sale, in the Catalog
        object model. Each [item](entity:CatalogItem) must have at least one

        item variation and can have at most 250 item variations.


        An item variation can be sellable, stockable, or both if it has a unit
        of measure for its count for the sold number of the variation, the
        stocked

        number of the variation, or both. For example, when a variation
        representing wine is stocked and sold by the bottle, the variation is
        both

        stockable and sellable. But when a variation of the wine is sold by the
        glass, the sold units cannot be used as a measure of the stocked units.
        This by-the-glass

        variation is sellable, but not stockable. To accurately keep track of
        the wine's inventory count at any time, the sellable count must be

        converted to stockable count. Typically, the seller defines this unit
        conversion. For example, 1 bottle equals 5 glasses. The Square API
        exposes

        the `stockable_conversion` property on the variation to specify the
        conversion. Thus, when two glasses of the wine are sold, the sellable
        count

        decreases by 2, and the stockable count automatically decreases by 0.4
        bottle according to the conversion.
      x-release-status: PUBLIC
      properties:
        item_id:
          type: string
          description: The ID of the `CatalogItem` associated with this item variation.
          nullable: true
        name:
          type: string
          description: >-
            The item variation's name. This is a searchable attribute for use in
            applicable query filters.


            Its value has a maximum length of 255 Unicode code points. However,
            when the parent [item](entity:CatalogItem)

            uses [item options](entity:CatalogItemOption), this attribute is
            auto-generated, read-only, and can be

            longer than 255 Unicode code points.
          nullable: true
        sku:
          type: string
          description: >-
            The item variation's SKU, if any. This is a searchable attribute for
            use in applicable query filters.
          nullable: true
        upc:
          type: string
          description: >-
            The universal product code (UPC) of the item variation, if any. This
            is a searchable attribute for use in applicable query filters.


            The value of this attribute should be a number of 12-14 digits
            long.  This restriction is enforced on the Square Seller Dashboard,

            Square Point of Sale or Retail Point of Sale apps, where this
            attribute shows in the GTIN field. If a non-compliant UPC value is
            assigned

            to this attribute using the API, the value is not editable on the
            Seller Dashboard, Square Point of Sale or Retail Point of Sale apps

            unless it is updated to fit the expected format.
          nullable: true
        ordinal:
          type: integer
          description: >-
            The order in which this item variation should be displayed. This
            value is read-only. On writes, the ordinal

            for each item variation within a parent `CatalogItem` is set
            according to the item variations's

            position. On reads, the value is not guaranteed to be sequential or
            unique.
          readOnly: true
        pricing_type:
          $ref: '#/components/schemas/CatalogPricingType'
          description: >-
            Indicates whether the item variation's price is fixed or determined
            at the time

            of sale.

            See [CatalogPricingType](#type-catalogpricingtype) for possible
            values
          nullable: true
        price_money:
          $ref: '#/components/schemas/Money'
          description: The item variation's price, if fixed pricing is used.
          nullable: true
        location_overrides:
          type: array
          items:
            $ref: '#/components/schemas/ItemVariationLocationOverrides'
          description: Per-location price and inventory overrides.
          nullable: true
        track_inventory:
          type: boolean
          description: If `true`, inventory tracking is active for the variation.
          nullable: true
        inventory_alert_type:
          $ref: '#/components/schemas/InventoryAlertType'
          description: >-
            Indicates whether the item variation displays an alert when its
            inventory quantity is less than or equal

            to its `inventory_alert_threshold`.

            See [InventoryAlertType](#type-inventoryalerttype) for possible
            values
          nullable: true
        inventory_alert_threshold:
          type: integer
          description: >-
            If the inventory quantity for the variation is less than or equal to
            this value and `inventory_alert_type`

            is `LOW_QUANTITY`, the variation displays an alert in the merchant
            dashboard.


            This value is always an integer.
          format: int64
          nullable: true
        user_data:
          type: string
          description: >-
            Arbitrary user metadata to associate with the item variation. This
            attribute value length is of Unicode code points.
          maxLength: 255
          nullable: true
        service_duration:
          type: integer
          description: >-
            If the `CatalogItem` that owns this item variation is of type

            `APPOINTMENTS_SERVICE`, then this is the duration of the service in
            milliseconds. For

            example, a 30 minute appointment would have the value `1800000`,
            which is equal to

            30 (minutes) * 60 (seconds per minute) * 1000 (milliseconds per
            second).
          format: int64
          nullable: true
        available_for_booking:
          type: boolean
          description: >-
            If the `CatalogItem` that owns this item variation is of type

            `APPOINTMENTS_SERVICE`, a bool representing whether this service is
            available for booking.
          x-release-status: BETA
          nullable: true
        item_option_values:
          type: array
          items:
            $ref: '#/components/schemas/CatalogItemOptionValueForItemVariation'
          description: >-
            List of item option values associated with this item variation.
            Listed

            in the same order as the item options of the parent item.
          nullable: true
        measurement_unit_id:
          type: string
          description: >-
            ID of the CatalogMeasurementUnit that is used to measure the
            quantity

            sold of this item variation. If left unset, the item will be sold in

            whole quantities.
          nullable: true
        sellable:
          type: boolean
          description: >-
            Whether this variation can be sold. The inventory count of a
            sellable variation indicates

            the number of units available for sale. When a variation is both
            stockable and sellable,

            its sellable inventory count can be smaller than or equal to its
            stockable count.
          x-release-status: BETA
          nullable: true
        stockable:
          type: boolean
          description: >-
            Whether stock is counted directly on this variation (TRUE) or only
            on its components (FALSE).

            When a variation is both stockable and sellable, the inventory count
            of a stockable variation keeps track of the number of units of this
            variation in stock

            and is not an indicator of the number of units of the variation that
            can be sold.
          x-release-status: BETA
          nullable: true
        image_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of images associated with this `CatalogItemVariation`
            instance.

            These images will be shown to customers in Square Online Store.
          nullable: true
        team_member_ids:
          type: array
          items:
            type: string
          description: >-
            Tokens of employees that can perform the service represented by this
            variation. Only valid for

            variations of type `APPOINTMENTS_SERVICE`.
          x-release-status: BETA
          nullable: true
        stockable_conversion:
          $ref: '#/components/schemas/CatalogStockConversion'
          description: >-
            The unit conversion rule, as prescribed by the
            [CatalogStockConversion](entity:CatalogStockConversion) type,

            that describes how this non-stockable (i.e., sellable/receivable)
            item variation is converted

            to/from the stockable item variation sharing the same parent item.
            With the stock conversion,

            you can accurately track inventory when an item variation is sold in
            one unit, but stocked in

            another unit.
          x-release-status: BETA
          nullable: true
    CatalogMeasurementUnit:
      type: object
      description: |-
        Represents the unit used to measure a `CatalogItemVariation` and
        specifies the precision for decimal quantities.
      x-release-status: PUBLIC
      properties:
        measurement_unit:
          $ref: '#/components/schemas/MeasurementUnit'
          description: >-
            Indicates the unit used to measure the quantity of a catalog item
            variation.
          nullable: true
        precision:
          type: integer
          description: >-
            An integer between 0 and 5 that represents the maximum number of

            positions allowed after the decimal in quantities measured with this
            unit.

            For example:


            - if the precision is 0, the quantity can be 1, 2, 3, etc.

            - if the precision is 1, the quantity can be 0.1, 0.2, etc.

            - if the precision is 2, the quantity can be 0.01, 0.12, etc.


            Default: 3
          nullable: true
    CatalogModifier:
      type: object
      description: >-
        A modifier applicable to items at the time of sale. An example of a
        modifier is a Cheese add-on to a Burger item.
      x-release-status: PUBLIC
      properties:
        name:
          type: string
          description: >-
            The modifier name.  This is a searchable attribute for use in
            applicable query filters, and its value length is of Unicode code
            points.
          maxLength: 255
          nullable: true
        price_money:
          $ref: '#/components/schemas/Money'
          description: The modifier price.
          nullable: true
        ordinal:
          type: integer
          description: >-
            Determines where this `CatalogModifier` appears in the
            `CatalogModifierList`.
          nullable: true
        modifier_list_id:
          type: string
          description: The ID of the `CatalogModifierList` associated with this modifier.
          nullable: true
        location_overrides:
          type: array
          items:
            $ref: '#/components/schemas/ModifierLocationOverrides'
          description: Location-specific price overrides.
          nullable: true
        image_id:
          type: string
          description: >-
            The ID of the image associated with this `CatalogModifier` instance.

            Currently this image is not displayed by Square, but is free to be
            displayed in 3rd party applications.
          x-release-status: BETA
          nullable: true
      example:
        object:
          modifier_data:
            name: Almond Milk
            price_money:
              amount: 250
              currency: USD
          present_at_all_locations: true
          type: MODIFIER
    CatalogModifierList:
      type: object
      description: >-
        For a text-based modifier, this encapsulates the modifier's text when
        its `modifier_type` is `TEXT`. 

        For example, to sell T-shirts with custom prints, a text-based modifier
        can be used to capture the buyer-supplied 

        text string to be selected for the T-shirt at the time of sale.


        For non text-based modifiers, this encapsulates a non-empty list of
        modifiers applicable to items 

        at the time of sale. Each element of the modifier list is a
        `CatalogObject` instance of the `MODIFIER` type.   

        For example, a "Condiments" modifier list applicable to a "Hot Dog" item

        may contain "Ketchup", "Mustard", and "Relish" modifiers. 


        A non text-based modifier can be applied to the modified item once or
        multiple times, if the `selection_type` field 

        is set to `SINGLE` or `MULTIPLE`, respectively. On the other hand, a
        text-based modifier can be applied to the item 

        only once and the `selection_type` field is always set to `SINGLE`.
      x-release-status: PUBLIC
      properties:
        name:
          type: string
          description: >-
            The name of the `CatalogModifierList` instance. This is a searchable
            attribute for use in applicable query filters, and its value length
            is of 

            Unicode code points.
          maxLength: 255
          nullable: true
        ordinal:
          type: integer
          description: >-
            The position of this `CatalogModifierList` within a list of
            `CatalogModifierList` instances.
          nullable: true
        selection_type:
          $ref: '#/components/schemas/CatalogModifierListSelectionType'
          description: >-
            Indicates whether a single (`SINGLE`) or multiple (`MULTIPLE`)
            modifiers from the list

            can be applied to a single `CatalogItem`.


            For text-based modifiers, the `selection_type` attribute is always
            `SINGLE`. The other value is ignored.

            See
            [CatalogModifierListSelectionType](#type-catalogmodifierlistselectiontype)
            for possible values
          nullable: true
        modifiers:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: >-
            A non-empty list of `CatalogModifier` objects to be included in the
            `CatalogModifierList`, 

            for non text-based modifiers when the `modifier_type` attribute is
            `LIST`. Each element of this list 

            is a `CatalogObject` instance of the `MODIFIER` type, containing the
            following attributes:

            ```

            {

            "id": "{{catalog_modifier_id}}",

            "type": "MODIFIER", 

            "modifier_data": {{a CatalogModifier instance>}} 

            }

            ```
          nullable: true
        image_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of images associated with this `CatalogModifierList`
            instance.

            Currently these images are not displayed on Square products, but may
            be displayed in 3rd-party applications.
          nullable: true
        modifier_type:
          $ref: '#/components/schemas/CatalogModifierListModifierType'
          description: >-
            The type of the modifier. 


            When this `modifier_type` value is `TEXT`,  the
            `CatalogModifierList` represents a text-based modifier. 

            When this `modifier_type` value is `LIST`, the `CatalogModifierList`
            contains a list of `CatalogModifier` objects.

            See
            [CatalogModifierListModifierType](#type-catalogmodifierlistmodifiertype)
            for possible values
          x-release-status: BETA
          nullable: true
        max_length:
          type: integer
          description: >-
            The maximum length, in Unicode points, of the text string of the
            text-based modifier as represented by 

            this `CatalogModifierList` object with the `modifier_type` set to
            `TEXT`.
          x-release-status: BETA
          nullable: true
        text_required:
          type: boolean
          description: >-
            Whether the text string must be a non-empty string (`true`) or not
            (`false`) for a text-based modifier

            as represented by this `CatalogModifierList` object with the
            `modifier_type` set to `TEXT`.
          x-release-status: BETA
          nullable: true
        internal_name:
          type: string
          description: >-
            A note for internal use by the business.   


            For example, for a text-based modifier applied to a T-shirt item, if
            the buyer-supplied text of "Hello, Kitty!"  

            is to be printed on the T-shirt, this `internal_name` attribute can
            be "Use italic face" as 

            an instruction for the business to follow.  


            For non text-based modifiers, this `internal_name` attribute can be 

            used to include SKUs, internal codes, or supplemental descriptions
            for internal use.
          maxLength: 512
          x-release-status: BETA
          nullable: true
      example:
        id: '#MilkType'
        modifier_list_data:
          allow_quantities: false
          modifiers:
            - modifier_data:
                name: Whole Milk
                price_money:
                  amount: 0
                  currency: USD
              present_at_all_locations: true
              type: MODIFIER
            - modifier_data:
                name: Almond Milk
                price_money:
                  amount: 250
                  currency: USD
              present_at_all_locations: true
              type: MODIFIER
            - modifier_data:
                name: Soy Milk
                price_money:
                  amount: 250
                  currency: USD
              present_at_all_locations: true
              type: MODIFIER
          name: Milk Type
          selection_type: SINGLE
        present_at_all_locations: true
        type: MODIFIER_LIST
    CatalogModifierListModifierType:
      type: string
      enum:
        - LIST
        - TEXT
      x-enum-elements:
        - name: LIST
          description: >-
            The `CatalogModifierList` instance is a non-empty list of non
            text-based modifiers.
        - name: TEXT
          description: The `CatalogModifierList` instance is a single text-based modifier.
      description: Defines the type of `CatalogModifierList`.
      x-release-status: BETA
    CatalogModifierListSelectionType:
      type: string
      enum:
        - SINGLE
        - MULTIPLE
      x-enum-elements:
        - name: SINGLE
          description: |-
            Indicates that a CatalogModifierList allows only a
            single CatalogModifier to be selected.
        - name: MULTIPLE
          description: |-
            Indicates that a CatalogModifierList allows multiple
            CatalogModifier to be selected.
      description: Indicates whether a CatalogModifierList supports multiple selections.
      x-release-status: PUBLIC
    CatalogModifierOverride:
      type: object
      description: >-
        Options to control how to override the default behavior of the specified
        modifier.
      x-release-status: PUBLIC
      required:
        - modifier_id
      properties:
        modifier_id:
          type: string
          description: >-
            The ID of the `CatalogModifier` whose default behavior is being
            overridden.
          minLength: 1
        on_by_default:
          type: boolean
          description: >-
            If `true`, this `CatalogModifier` should be selected by default for
            this `CatalogItem`.
          nullable: true
    CatalogObject:
      type: object
      description: >-
        The wrapper object for the catalog entries of a given object type.


        Depending on the `type` attribute value, a `CatalogObject` instance
        assumes a type-specific data to yield the corresponding type of catalog
        object.


        For example, if `type=ITEM`, the `CatalogObject` instance must have the
        ITEM-specific data set on the `item_data` attribute. The resulting
        `CatalogObject` instance is also a `CatalogItem` instance.


        In general, if `type=<OBJECT_TYPE>`, the `CatalogObject` instance must
        have the `<OBJECT_TYPE>`-specific data set on the `<object_type>_data`
        attribute. The resulting `CatalogObject` instance is also a
        `Catalog<ObjectType>` instance.


        For a more detailed discussion of the Catalog data model, please see the

        [Design a
        Catalog](https://developer.squareup.com/docs/catalog-api/design-a-catalog)
        guide.
      x-release-status: PUBLIC
      required:
        - type
        - id
      properties:
        type:
          $ref: '#/components/schemas/CatalogObjectType'
          description: >-
            The type of this object. Each object type has expected

            properties expressed in a structured format within its corresponding
            `*_data` field below.

            See [CatalogObjectType](#type-catalogobjecttype) for possible values
        id:
          type: string
          description: >-
            An identifier to reference this object in the catalog. When a new
            `CatalogObject`

            is inserted, the client should set the id to a temporary identifier
            starting with

            a "`#`" character. Other objects being inserted or updated within
            the same request

            may use this identifier to refer to the new object.


            When the server receives the new object, it will supply a unique
            identifier that

            replaces the temporary identifier for all future references.
          minLength: 1
        updated_at:
          type: string
          description: >-
            Last modification
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)
            in RFC 3339 format, e.g., `"2016-08-15T23:59:33.123Z"`

            would indicate the UTC time (denoted by `Z`) of August 15, 2016 at
            23:59:33 and 123 milliseconds.
          readOnly: true
        version:
          type: integer
          description: >-
            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.
          format: int64
        is_deleted:
          type: boolean
          description: >-
            If `true`, the object has been deleted from the database. Must be
            `false` for new objects

            being inserted. When deleted, the `updated_at` field will equal the
            deletion time.
          nullable: true
        custom_attribute_values:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CatalogCustomAttributeValue'
          description: >-
            A map (key-value pairs) of application-defined custom attribute
            values. The value of a key-value pair

            is a
            [CatalogCustomAttributeValue](entity:CatalogCustomAttributeValue)
            object. The key is the `key` attribute

            value defined in the associated
            [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition)

            object defined by the application making the request.


            If the `CatalogCustomAttributeDefinition` object is

            defined by another application, the
            `CatalogCustomAttributeDefinition`'s key attribute value is prefixed
            by

            the defining application ID. For example, if the
            `CatalogCustomAttributeDefinition` has a `key` attribute of

            `"cocoa_brand"` and the defining application ID is `"abcd1234"`, the
            key in the map is `"abcd1234:cocoa_brand"`

            if the application making the request is different from the
            application defining the custom attribute definition.

            Otherwise, the key used in the map is simply `"cocoa_brand"`.


            Application-defined custom attributes are set at a global
            (location-independent) level.

            Custom attribute values are intended to store additional information
            about a catalog object

            or associations with an entity in another system. Do not use custom
            attributes

            to store any sensitive information (personally identifiable
            information, card details, etc.).
          nullable: true
        catalog_v1_ids:
          type: array
          items:
            $ref: '#/components/schemas/CatalogV1Id'
          description: >-
            The Connect v1 IDs for this object at each location where it is
            present, where they

            differ from the object's Connect V2 ID. The field will only be
            present for objects that

            have been created or modified by legacy APIs.
          nullable: true
        present_at_all_locations:
          type: boolean
          description: >-
            If `true`, this object is present at all locations (including future
            locations), except where specified in

            the `absent_at_location_ids` field. If `false`, this object is not
            present at any locations (including future locations),

            except where specified in the `present_at_location_ids` field. If
            not specified, defaults to `true`.
          nullable: true
        present_at_location_ids:
          type: array
          items:
            type: string
          description: >-
            A list of locations where the object is present, even if
            `present_at_all_locations` is `false`.

            This can include locations that are deactivated.
          nullable: true
        absent_at_location_ids:
          type: array
          items:
            type: string
          description: >-
            A list of locations where the object is not present, even if
            `present_at_all_locations` is `true`.

            This can include locations that are deactivated.
          nullable: true
        item_data:
          $ref: '#/components/schemas/CatalogItem'
          description: >-
            Structured data for a `CatalogItem`, set for CatalogObjects of type
            `ITEM`.
          nullable: true
        category_data:
          $ref: '#/components/schemas/CatalogCategory'
          description: >-
            Structured data for a `CatalogCategory`, set for CatalogObjects of
            type `CATEGORY`.
          nullable: true
        item_variation_data:
          $ref: '#/components/schemas/CatalogItemVariation'
          description: >-
            Structured data for a `CatalogItemVariation`, set for CatalogObjects
            of type `ITEM_VARIATION`.
          nullable: true
        tax_data:
          $ref: '#/components/schemas/CatalogTax'
          description: >-
            Structured data for a `CatalogTax`, set for CatalogObjects of type
            `TAX`.
          nullable: true
        discount_data:
          $ref: '#/components/schemas/CatalogDiscount'
          description: >-
            Structured data for a `CatalogDiscount`, set for CatalogObjects of
            type `DISCOUNT`.
          nullable: true
        modifier_list_data:
          $ref: '#/components/schemas/CatalogModifierList'
          description: >-
            Structured data for a `CatalogModifierList`, set for CatalogObjects
            of type `MODIFIER_LIST`.
          nullable: true
        modifier_data:
          $ref: '#/components/schemas/CatalogModifier'
          description: >-
            Structured data for a `CatalogModifier`, set for CatalogObjects of
            type `MODIFIER`.
          nullable: true
        time_period_data:
          $ref: '#/components/schemas/CatalogTimePeriod'
          description: >-
            Structured data for a `CatalogTimePeriod`, set for CatalogObjects of
            type `TIME_PERIOD`.
          nullable: true
        product_set_data:
          $ref: '#/components/schemas/CatalogProductSet'
          description: >-
            Structured data for a `CatalogProductSet`, set for CatalogObjects of
            type `PRODUCT_SET`.
          nullable: true
        pricing_rule_data:
          $ref: '#/components/schemas/CatalogPricingRule'
          description: >-
            Structured data for a `CatalogPricingRule`, set for CatalogObjects
            of type `PRICING_RULE`.

            A `CatalogPricingRule` object often works with a `CatalogProductSet`
            object or a `CatalogTimePeriod` object.
          nullable: true
        image_data:
          $ref: '#/components/schemas/CatalogImage'
          description: >-
            Structured data for a `CatalogImage`, set for CatalogObjects of type
            `IMAGE`.
          nullable: true
        measurement_unit_data:
          $ref: '#/components/schemas/CatalogMeasurementUnit'
          description: >-
            Structured data for a `CatalogMeasurementUnit`, set for
            CatalogObjects of type `MEASUREMENT_UNIT`.
          nullable: true
        subscription_plan_data:
          $ref: '#/components/schemas/CatalogSubscriptionPlan'
          description: >-
            Structured data for a `CatalogSubscriptionPlan`, set for
            CatalogObjects of type `SUBSCRIPTION_PLAN`.
          nullable: true
        item_option_data:
          $ref: '#/components/schemas/CatalogItemOption'
          description: >-
            Structured data for a `CatalogItemOption`, set for CatalogObjects of
            type `ITEM_OPTION`.
          nullable: true
        item_option_value_data:
          $ref: '#/components/schemas/CatalogItemOptionValue'
          description: >-
            Structured data for a `CatalogItemOptionValue`, set for
            CatalogObjects of type `ITEM_OPTION_VAL`.
          nullable: true
        custom_attribute_definition_data:
          $ref: '#/components/schemas/CatalogCustomAttributeDefinition'
          description: >-
            Structured data for a `CatalogCustomAttributeDefinition`, set for
            CatalogObjects of type `CUSTOM_ATTRIBUTE_DEFINITION`.
          nullable: true
        quick_amounts_settings_data:
          $ref: '#/components/schemas/CatalogQuickAmountsSettings'
          description: >-
            Structured data for a `CatalogQuickAmountsSettings`, set for
            CatalogObjects of type `QUICK_AMOUNTS_SETTINGS`.
          x-release-status: BETA
          nullable: true
        subscription_plan_variation_data:
          $ref: '#/components/schemas/CatalogSubscriptionPlanVariation'
          description: >-
            Structured data for a `CatalogSubscriptionPlanVariation`, set for
            CatalogObjects of type `SUBSCRIPTION_PLAN_VARIATION`.
          nullable: true
        availability_period_data:
          $ref: '#/components/schemas/CatalogAvailabilityPeriod'
          description: >-
            Structured data for a `CatalogAvailabilityPeriod`, set for
            CatalogObjects of type `AVAILABILITY_PERIOD`.
          nullable: true
      example:
        catalog_object:
          absent_at_location_ids:
            - '{{ LOCATIONID-1 }}'
            - '{{ LOCATIONID-N }}'
          category_data: '{{ CatalogCategory object only if type=CATEGORY }}'
          connect_v1_ids:
            catalog_v1_id: '{{ itemID from Catalog v1 }}'
            location_id: '{{ location where v1 ID is used }}'
          discount_data: '{{ CatalogDiscount object only if type=DISCOUNT }}'
          id: '{{ set by Catalog during object creation }}'
          is_deleted: '{{ [true | false] }}'
          item_data: '{{ CatalogItem object only if type=ITEM }}'
          item_variation_data: '{{ CatalogItemVariation object only if type=ITEM_VARIATION }}'
          modifier_data: '{{ CatalogModifier object only if type=MODIFIER }}'
          modifier_list_data: '{{ CatalogModifierList object only if type=MODIFIER_LIST }}'
          present_at_all_locations: '{{ [true | false] }}'
          present_at_location_ids:
            - '{{ LOCATIONID-1 }}'
            - '{{ LOCATIONID-N }}'
          tax_data: '{{ CatalogTax object only if type=TAX }}'
          type: >-
            {{ [ITEM | ITEM_VARIATION | MODIFIER | MODIFIER_LIST | CATEGORY |
            DISCOUNT | TAX] }}
          updated_at: '{{ date & time of most recent update }}'
          version: '{{ version of the CatalogObject }}'
    CatalogObjectBatch:
      type: object
      description: A batch of catalog objects.
      x-release-status: PUBLIC
      required:
        - objects
      properties:
        objects:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: A list of CatalogObjects belonging to this batch.
    CatalogObjectCategory:
      type: object
      description: >-
        A category that can be assigned to an item or a parent category that can
        be assigned 

        to another category. For example, a clothing category can be assigned to
        a t-shirt item or 

        be made as the parent category to the pants category.
      x-release-status: BETA
      properties:
        id:
          type: string
          description: The ID of the object's category.
        ordinal:
          type: integer
          description: The order of the object within the context of the category.
          format: int64
          nullable: true
    CatalogObjectReference:
      type: object
      description: >-
        A reference to a Catalog object at a specific version. In general this
        is

        used as an entry point into a graph of catalog objects, where the
        objects exist

        at a specific version.
      x-release-status: PUBLIC
      properties:
        object_id:
          type: string
          description: The ID of the referenced object.
          nullable: true
        catalog_version:
          type: integer
          description: The version of the object.
          format: int64
          nullable: true
    CatalogObjectType:
      type: string
      enum:
        - ITEM
        - IMAGE
        - CATEGORY
        - ITEM_VARIATION
        - TAX
        - DISCOUNT
        - MODIFIER_LIST
        - MODIFIER
        - PRICING_RULE
        - PRODUCT_SET
        - TIME_PERIOD
        - MEASUREMENT_UNIT
        - SUBSCRIPTION_PLAN_VARIATION
        - ITEM_OPTION
        - ITEM_OPTION_VAL
        - CUSTOM_ATTRIBUTE_DEFINITION
        - QUICK_AMOUNTS_SETTINGS
        - SUBSCRIPTION_PLAN
        - AVAILABILITY_PERIOD
      x-enum-elements:
        - name: ITEM
          description: >-
            The `CatalogObject` instance is of the
            [CatalogItem](entity:CatalogItem) type and represents an item. The
            item-specific data

            must be set on the `item_data` field.
        - name: IMAGE
          description: >-
            The `CatalogObject` instance is of the
            [CatalogImage](entity:CatalogImage) type and represents an image.
            The image-specific data

            must be set on the `image_data` field.
        - name: CATEGORY
          description: >-
            The `CatalogObject` instance is of the
            [CatalogCategory](entity:CatalogCategory) type and represents a
            category. The category-specific data

            must be set on the `category_data` field.
        - name: ITEM_VARIATION
          description: >-
            The `CatalogObject` instance is of the 
            [CatalogItemVariation](entity:CatalogItemVariation) type and
            represents an item variation, also referred to as variation.

            The item variation-specific data must be set on the
            `item_variation_data` field.
        - name: TAX
          description: >-
            The `CatalogObject` instance is of the
            [CatalogTax](entity:CatalogTax) type and represents a tax. The
            tax-specific data

            must be set on the `tax_data` field.
        - name: DISCOUNT
          description: >-
            The `CatalogObject` instance is of the
            [CatalogDiscount](entity:CatalogDiscount) type and represents a
            discount. The discount-specific data

            must be set on the `discount_data` field.
        - name: MODIFIER_LIST
          description: >-
            The `CatalogObject` instance is of the
            [CatalogModifierList](entity:CatalogModifierList) type and
            represents a modifier list.

            The modifier-list-specific data must be set on the
            `modifier_list_data` field.
        - name: MODIFIER
          description: >-
            The `CatalogObject` instance is of the
            [CatalogModifier](entity:CatalogModifier) type and represents a
            modifier. The modifier-specific data

            must be set on the `modifier_data` field.
        - name: PRICING_RULE
          description: >-
            The `CatalogObject` instance is of the
            [CatalogPricingRule](entity:CatalogPricingRule) type and represents
            a pricing rule. The pricing-rule-specific data

            must be set on the `pricing_rule_data` field.
        - name: PRODUCT_SET
          description: >-
            The `CatalogObject` instance is of the
            [CatalogProductSet](entity:CatalogProductSet) type and represents a
            product set.

            The product-set-specific data will be stored in the
            `product_set_data` field.
        - name: TIME_PERIOD
          description: >-
            The `CatalogObject` instance is of the
            [CatalogTimePeriod](entity:CatalogTimePeriod) type and represents a
            time period.

            The time-period-specific data must be set on the `time_period_data`
            field.
        - name: MEASUREMENT_UNIT
          description: >-
            The `CatalogObject` instance is of the
            [CatalogMeasurementUnit](entity:CatalogMeasurementUnit) type and
            represents a measurement unit specifying the unit of

            measure and precision in which an item variation is sold. The
            measurement-unit-specific data must set on the
            `measurement_unit_data` field.
        - name: SUBSCRIPTION_PLAN_VARIATION
          description: >-
            The `CatalogObject` instance is of the
            [CatalogSubscriptionPlan](entity:CatalogSubscriptionPlan) type and
            represents a subscription plan.

            The subscription-plan-specific data must be stored on the
            `subscription_plan_data` field.
        - name: ITEM_OPTION
          description: >-
            The `CatalogObject` instance is of the
            [CatalogItemOption](entity:CatalogItemOption) type and represents a
            list of options (such as a color or size of a T-shirt)

            that can be assigned to item variations. The item-option-specific
            data must be on the `item_option_data` field.
        - name: ITEM_OPTION_VAL
          description: >-
            The `CatalogObject` instance is of the
            [CatalogItemOptionValue](entity:CatalogItemOptionValue) type and
            represents a value associated with one or more item options.

            For example, an item option of "Size" may have item option values
            such as "Small" or "Medium".

            The item-option-value-specific data must be on the
            `item_option_value_data` field.
        - name: CUSTOM_ATTRIBUTE_DEFINITION
          description: >-
            The `CatalogObject` instance is of the
            [CatalogCustomAttributeDefinition](entity:CatalogCustomAttributeDefinition)
            type and represents the definition of a custom attribute.

            The custom-attribute-definition-specific data must be set on the
            `custom_attribute_definition_data` field.
        - name: QUICK_AMOUNTS_SETTINGS
          description: >-
            The `CatalogObject` instance is of the
            [CatalogQuickAmountsSettings](entity:CatalogQuickAmountsSettings)
            type and represents settings to configure preset charges for quick
            payments at each location.

            For example, a location may have a list of both AUTO and MANUAL
            quick amounts that are set to DISABLED.

            The quick-amounts-settings-specific data must be set on the
            `quick_amounts_settings_data` field.
        - name: SUBSCRIPTION_PLAN
          description: >-
            The `CatalogObject` instance is of the
            [CatalogSubscriptionPlan](entity:CatalogSubscriptionPlan) type and
            represents a subscription plan.

            The subscription plan specific data must be stored on the
            `subscription_plan_data` field.
        - name: AVAILABILITY_PERIOD
          description: >-
            The `CatalogObject` instance is of the
            [CatalogAvailabilityPeriod](entity:CatalogAvailabilityPeriod) type
            and represents an availability period.

            The availability period specific data must be stored on the
            `availability_period_data` field.
      description: >-
        Possible types of CatalogObjects returned from the catalog, each

        containing type-specific properties in the `*_data` field corresponding
        to the specified object type.
      x-release-status: PUBLIC
    CatalogPricingRule:
      type: object
      description: >-
        Defines how discounts are automatically applied to a set of items that
        match the pricing rule

        during the active time period.
      x-release-status: PUBLIC
      properties:
        name:
          type: string
          description: >-
            User-defined name for the pricing rule. For example, "Buy one get
            one

            free" or "10% off".
          nullable: true
        time_period_ids:
          type: array
          items:
            type: string
          description: >-
            A list of unique IDs for the catalog time periods when

            this pricing rule is in effect. If left unset, the pricing rule is
            always

            in effect.
          nullable: true
        discount_id:
          type: string
          description: |-
            Unique ID for the `CatalogDiscount` to take off
            the price of all matched items.
          nullable: true
        match_products_id:
          type: string
          description: >-
            Unique ID for the `CatalogProductSet` that will be matched by this
            rule. A match rule

            matches within the entire cart, and can match multiple times. This
            field will always be set.
          nullable: true
        apply_products_id:
          type: string
          description: >-
            __Deprecated__: Please use the `exclude_products_id` field to apply

            an exclude set instead. Exclude sets allow better control over
            quantity

            ranges and offer more flexibility for which matched items receive a
            discount.


            `CatalogProductSet` to apply the pricing to.

            An apply rule matches within the subset of the cart that fits the
            match rules (the match set).

            An apply rule can only match once in the match set.

            If not supplied, the pricing will be applied to all products in the
            match set.

            Other products retain their base price, or a price generated by
            other rules.
          x-release-status: DEPRECATED
          nullable: true
        exclude_products_id:
          type: string
          description: >-
            `CatalogProductSet` to exclude from the pricing rule.

            An exclude rule matches within the subset of the cart that fits the
            match rules (the match set).

            An exclude rule can only match once in the match set.

            If not supplied, the pricing will be applied to all products in the
            match set.

            Other products retain their base price, or a price generated by
            other rules.
          nullable: true
        valid_from_date:
          type: string
          description: >-
            Represents the date the Pricing Rule is valid from. Represented in
            RFC 3339 full-date format (YYYY-MM-DD).
          nullable: true
        valid_from_local_time:
          type: string
          description: >-
            Represents the local time the pricing rule should be valid from.
            Represented in RFC 3339 partial-time format

            (HH:MM:SS). Partial seconds will be truncated.
          nullable: true
        valid_until_date:
          type: string
          description: >-
            Represents the date the Pricing Rule is valid until. Represented in
            RFC 3339 full-date format (YYYY-MM-DD).
          nullable: true
        valid_until_local_time:
          type: string
          description: >-
            Represents the local time the pricing rule should be valid until.
            Represented in RFC 3339 partial-time format

            (HH:MM:SS). Partial seconds will be truncated.
          nullable: true
        exclude_strategy:
          $ref: '#/components/schemas/ExcludeStrategy'
          description: >-
            If an `exclude_products_id` was given, controls which subset of
            matched

            products is excluded from any discounts.


            Default value: `LEAST_EXPENSIVE`

            See [ExcludeStrategy](#type-excludestrategy) for possible values
          nullable: true
        minimum_order_subtotal_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The minimum order subtotal (before discounts or taxes are applied)
            that must be met before this rule may be applied.
          nullable: true
        customer_group_ids_any:
          type: array
          items:
            type: string
          description: >-
            A list of IDs of customer groups, the members of which are eligible
            for discounts specified in this pricing rule.

            Notice that a group ID is generated by the Customers API.

            If this field is not set, the specified discount applies to matched
            products sold to anyone whether the buyer

            has a customer profile created or not. If this
            `customer_group_ids_any` field is set, the specified discount

            applies only to matched products sold to customers belonging to the
            specified customer groups.
          nullable: true
    CatalogPricingType:
      type: string
      enum:
        - FIXED_PRICING
        - VARIABLE_PRICING
      x-enum-elements:
        - name: FIXED_PRICING
          description: The catalog item variation's price is fixed.
        - name: VARIABLE_PRICING
          description: The catalog item variation's price is entered at the time of sale.
      description: >-
        Indicates whether the price of a CatalogItemVariation should be entered
        manually at the time of sale.
      x-release-status: PUBLIC
    CatalogProductSet:
      type: object
      description: >-
        Represents a collection of catalog objects for the purpose of applying a

        `PricingRule`. Including a catalog object will include all of its
        subtypes.

        For example, including a category in a product set will include all of
        its

        items and associated item variations in the product set. Including an
        item in

        a product set will also include its item variations.
      x-release-status: PUBLIC
      properties:
        name:
          type: string
          description: >-
            User-defined name for the product set. For example, "Clearance
            Items"

            or "Winter Sale Items".
          nullable: true
        product_ids_any:
          type: array
          items:
            type: string
          description: >2-
             Unique IDs for any `CatalogObject` included in this product set. Any
            number of these catalog objects can be in an order for a pricing
            rule to apply.


            This can be used with `product_ids_all` in a parent
            `CatalogProductSet` to

            match groups of products for a bulk discount, such as a discount for
            an

            entree and side combo.


            Only one of `product_ids_all`, `product_ids_any`, or `all_products`
            can be set.


            Max: 500 catalog object IDs.
          nullable: true
        product_ids_all:
          type: array
          items:
            type: string
          description: >-
            Unique IDs for any `CatalogObject` included in this product set.

            All objects in this set must be included in an order for a pricing
            rule to apply.


            Only one of `product_ids_all`, `product_ids_any`, or `all_products`
            can be set.


            Max: 500 catalog object IDs.
          nullable: true
        quantity_exact:
          type: integer
          description: >-
            If set, there must be exactly this many items from `products_any` or
            `products_all`

            in the cart for the discount to apply.


            Cannot be combined with either `quantity_min` or `quantity_max`.
          format: int64
          nullable: true
        quantity_min:
          type: integer
          description: >-
            If set, there must be at least this many items from `products_any`
            or `products_all`

            in a cart for the discount to apply. See `quantity_exact`. Defaults
            to 0 if

            `quantity_exact`, `quantity_min` and `quantity_max` are all
            unspecified.
          format: int64
          nullable: true
        quantity_max:
          type: integer
          description: >-
            If set, the pricing rule will apply to a maximum of this many items
            from

            `products_any` or `products_all`.
          format: int64
          nullable: true
        all_products:
          type: boolean
          description: >-
            If set to `true`, the product set will include every item in the
            catalog.

            Only one of `product_ids_all`, `product_ids_any`, or `all_products`
            can be set.
          nullable: true
    CatalogQuery:
      type: object
      description: >-
        A query composed of one or more different types of filters to narrow the
        scope of targeted objects when calling the `SearchCatalogObjects`
        endpoint.


        Although a query can have multiple filters, only certain query types can
        be combined per call to
        [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects).

        Any combination of the following types may be used together:

        - [exact_query](entity:CatalogQueryExact)

        - [prefix_query](entity:CatalogQueryPrefix)

        - [range_query](entity:CatalogQueryRange)

        - [sorted_attribute_query](entity:CatalogQuerySortedAttribute)

        - [text_query](entity:CatalogQueryText)


        All other query types cannot be combined with any others.


        When a query filter is based on an attribute, the attribute must be
        searchable.

        Searchable attributes are listed as follows, along their parent types
        that can be searched for with applicable query filters.


        Searchable attribute and objects queryable by searchable attributes:

        - `name`:  `CatalogItem`, `CatalogItemVariation`, `CatalogCategory`,
        `CatalogTax`, `CatalogDiscount`, `CatalogModifier`,
        `CatalogModifierList`, `CatalogItemOption`, `CatalogItemOptionValue`

        - `description`: `CatalogItem`, `CatalogItemOptionValue`

        - `abbreviation`: `CatalogItem`

        - `upc`: `CatalogItemVariation`

        - `sku`: `CatalogItemVariation`

        - `caption`: `CatalogImage`

        - `display_name`: `CatalogItemOption`


        For example, to search for [CatalogItem](entity:CatalogItem) objects by
        searchable attributes, you can use

        the `"name"`, `"description"`, or `"abbreviation"` attribute in an
        applicable query filter.
      x-release-status: PUBLIC
      properties:
        sorted_attribute_query:
          $ref: '#/components/schemas/CatalogQuerySortedAttribute'
          description: >-
            A query expression to sort returned query result by the given
            attribute.
          nullable: true
        exact_query:
          $ref: '#/components/schemas/CatalogQueryExact'
          description: >-
            An exact query expression to return objects with attribute name and
            value

            matching the specified attribute name and value exactly. Value
            matching is case insensitive.
          nullable: true
        set_query:
          $ref: '#/components/schemas/CatalogQuerySet'
          description: >-
            A set query expression to return objects with attribute name and
            value

            matching the specified attribute name and any of the specified
            attribute values exactly.

            Value matching is case insensitive.
          nullable: true
        prefix_query:
          $ref: '#/components/schemas/CatalogQueryPrefix'
          description: >-
            A prefix query expression to return objects with attribute values

            that have a prefix matching the specified string value. Value
            matching is case insensitive.
          nullable: true
        range_query:
          $ref: '#/components/schemas/CatalogQueryRange'
          description: |-
            A range query expression to return objects with numeric values
            that lie in the specified range.
          nullable: true
        text_query:
          $ref: '#/components/schemas/CatalogQueryText'
          description: >-
            A text query expression to return objects whose searchable
            attributes contain all of the given

            keywords, irrespective of their order. For example, if a
            `CatalogItem` contains custom attribute values of

            `{"name": "t-shirt"}` and `{"description": "Small, Purple"}`, the
            query filter of `{"keywords": ["shirt", "sma", "purp"]}`

            returns this item.
          nullable: true
        items_for_tax_query:
          $ref: '#/components/schemas/CatalogQueryItemsForTax'
          description: >-
            A query expression to return items that have any of the specified
            taxes (as identified by the corresponding `CatalogTax` object IDs)
            enabled.
          nullable: true
        items_for_modifier_list_query:
          $ref: '#/components/schemas/CatalogQueryItemsForModifierList'
          description: >-
            A query expression to return items that have any of the given
            modifier list (as identified by the corresponding
            `CatalogModifierList`s IDs) enabled.
          nullable: true
        items_for_item_options_query:
          $ref: '#/components/schemas/CatalogQueryItemsForItemOptions'
          description: >-
            A query expression to return items that contains the specified item
            options (as identified the corresponding `CatalogItemOption` IDs).
          nullable: true
        item_variations_for_item_option_values_query:
          $ref: '#/components/schemas/CatalogQueryItemVariationsForItemOptionValues'
          description: >-
            A query expression to return item variations (of the
            [CatalogItemVariation](entity:CatalogItemVariation) type) that

            contain all of the specified `CatalogItemOption` IDs.
          nullable: true
    CatalogQueryExact:
      type: object
      description: >-
        The query filter to return the search result by exact match of the
        specified attribute name and value.
      x-release-status: PUBLIC
      required:
        - attribute_name
        - attribute_value
      properties:
        attribute_name:
          type: string
          description: >-
            The name of the attribute to be searched. Matching of the attribute
            name is exact.
          minLength: 1
        attribute_value:
          type: string
          description: >-
            The desired value of the search attribute. Matching of the attribute
            value is case insensitive and can be partial.

            For example, if a specified value of "sma", objects with the named
            attribute value of "Small", "small" are both matched.
    CatalogQueryItemVariationsForItemOptionValues:
      type: object
      description: >-
        The query filter to return the item variations containing the specified
        item option value IDs.
      x-release-status: PUBLIC
      properties:
        item_option_value_ids:
          type: array
          items:
            type: string
          description: >-
            A set of `CatalogItemOptionValue` IDs to be used to find associated

            `CatalogItemVariation`s. All ItemVariations that contain all of the
            given

            Item Option Values (in any order) will be returned.
          nullable: true
    CatalogQueryItemsForItemOptions:
      type: object
      description: >-
        The query filter to return the items containing the specified item
        option IDs.
      x-release-status: PUBLIC
      properties:
        item_option_ids:
          type: array
          items:
            type: string
          description: >-
            A set of `CatalogItemOption` IDs to be used to find associated

            `CatalogItem`s. All Items that contain all of the given Item Options
            (in any order)

            will be returned.
          nullable: true
    CatalogQueryItemsForModifierList:
      type: object
      description: >-
        The query filter to return the items containing the specified modifier
        list IDs.
      x-release-status: PUBLIC
      required:
        - modifier_list_ids
      properties:
        modifier_list_ids:
          type: array
          items:
            type: string
          description: >-
            A set of `CatalogModifierList` IDs to be used to find associated
            `CatalogItem`s.
    CatalogQueryItemsForTax:
      type: object
      description: The query filter to return the items containing the specified tax IDs.
      x-release-status: PUBLIC
      required:
        - tax_ids
      properties:
        tax_ids:
          type: array
          items:
            type: string
          description: >-
            A set of `CatalogTax` IDs to be used to find associated
            `CatalogItem`s.
    CatalogQueryPrefix:
      type: object
      description: >-
        The query filter to return the search result whose named attribute
        values are prefixed by the specified attribute value.
      x-release-status: PUBLIC
      required:
        - attribute_name
        - attribute_prefix
      properties:
        attribute_name:
          type: string
          description: The name of the attribute to be searched.
          minLength: 1
        attribute_prefix:
          type: string
          description: The desired prefix of the search attribute value.
          minLength: 1
    CatalogQueryRange:
      type: object
      description: >-
        The query filter to return the search result whose named attribute
        values fall between the specified range.
      x-release-status: PUBLIC
      required:
        - attribute_name
      properties:
        attribute_name:
          type: string
          description: The name of the attribute to be searched.
          minLength: 1
        attribute_min_value:
          type: integer
          description: The desired minimum value for the search attribute (inclusive).
          format: int64
          nullable: true
        attribute_max_value:
          type: integer
          description: The desired maximum value for the search attribute (inclusive).
          format: int64
          nullable: true
    CatalogQuerySet:
      type: object
      description: >-
        The query filter to return the search result(s) by exact match of the
        specified `attribute_name` and any of

        the `attribute_values`.
      x-release-status: PUBLIC
      required:
        - attribute_name
        - attribute_values
      properties:
        attribute_name:
          type: string
          description: >-
            The name of the attribute to be searched. Matching of the attribute
            name is exact.
          minLength: 1
        attribute_values:
          type: array
          items:
            type: string
          description: >-
            The desired values of the search attribute. Matching of the
            attribute values is exact and case insensitive.

            A maximum of 250 values may be searched in a request.
    CatalogQuerySortedAttribute:
      type: object
      description: The query expression to specify the key to sort search results.
      x-release-status: PUBLIC
      required:
        - attribute_name
      properties:
        attribute_name:
          type: string
          description: The attribute whose value is used as the sort key.
          minLength: 1
        initial_attribute_value:
          type: string
          description: >-
            The first attribute value to be returned by the query. Ascending
            sorts will return only

            objects with this value or greater, while descending sorts will
            return only objects with this value

            or less. If unset, start at the beginning (for ascending sorts) or
            end (for descending sorts).
          nullable: true
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: >-
            The desired sort order, `"ASC"` (ascending) or `"DESC"`
            (descending).

            See [SortOrder](#type-sortorder) for possible values
          nullable: true
    CatalogQueryText:
      type: object
      description: >-
        The query filter to return the search result whose searchable attribute
        values contain all of the specified keywords or tokens, independent of
        the token order or case.
      x-release-status: PUBLIC
      required:
        - keywords
      properties:
        keywords:
          type: array
          items:
            type: string
          description: >-
            A list of 1, 2, or 3 search keywords. Keywords with fewer than 3
            alphanumeric characters are ignored.
    CatalogQuickAmount:
      type: object
      description: Represents a Quick Amount in the Catalog.
      x-release-status: BETA
      required:
        - type
        - amount
      properties:
        type:
          $ref: '#/components/schemas/CatalogQuickAmountType'
          description: >-
            Represents the type of the Quick Amount.

            See [CatalogQuickAmountType](#type-catalogquickamounttype) for
            possible values
        amount:
          $ref: '#/components/schemas/Money'
          description: Represents the actual amount of the Quick Amount with Money type.
        score:
          type: integer
          description: >-
            Describes the ranking of the Quick Amount provided by machine
            learning model, in the range [0, 100].

            MANUAL type amount will always have score = 100.
          format: int64
          nullable: true
        ordinal:
          type: integer
          description: The order in which this Quick Amount should be displayed.
          format: int64
          nullable: true
    CatalogQuickAmountType:
      type: string
      enum:
        - QUICK_AMOUNT_TYPE_MANUAL
        - QUICK_AMOUNT_TYPE_AUTO
      x-enum-elements:
        - name: QUICK_AMOUNT_TYPE_MANUAL
          description: Quick Amount is created manually by the seller.
        - name: QUICK_AMOUNT_TYPE_AUTO
          description: >-
            Quick Amount is generated automatically by machine learning
            algorithms.
      description: Determines the type of a specific Quick Amount.
      x-release-status: BETA
    CatalogQuickAmountsSettings:
      type: object
      description: >-
        A parent Catalog Object model represents a set of Quick Amounts and the
        settings control the amounts.
      x-release-status: BETA
      required:
        - option
      properties:
        option:
          $ref: '#/components/schemas/CatalogQuickAmountsSettingsOption'
          description: >-
            Represents the option seller currently uses on Quick Amounts.

            See
            [CatalogQuickAmountsSettingsOption](#type-catalogquickamountssettingsoption)
            for possible values
        eligible_for_auto_amounts:
          type: boolean
          description: >-
            Represents location's eligibility for auto amounts

            The boolean should be consistent with whether there are AUTO amounts
            in the `amounts`.
          nullable: true
        amounts:
          type: array
          items:
            $ref: '#/components/schemas/CatalogQuickAmount'
          description: Represents a set of Quick Amounts at this location.
          nullable: true
    CatalogQuickAmountsSettingsOption:
      type: string
      enum:
        - DISABLED
        - MANUAL
        - AUTO
      x-enum-elements:
        - name: DISABLED
          description: Option for seller to disable Quick Amounts.
        - name: MANUAL
          description: Option for seller to choose manually created Quick Amounts.
        - name: AUTO
          description: Option for seller to choose automatically created Quick Amounts.
      description: Determines a seller's option on Quick Amounts feature.
      x-release-status: BETA
    CatalogStockConversion:
      type: object
      description: >-
        Represents the rule of conversion between a stockable
        [CatalogItemVariation](entity:CatalogItemVariation)

        and a non-stockable sell-by or receive-by `CatalogItemVariation` that

        share the same underlying stock.
      x-release-status: BETA
      required:
        - stockable_item_variation_id
        - stockable_quantity
        - nonstockable_quantity
      properties:
        stockable_item_variation_id:
          type: string
          description: >-
            References to the stockable
            [CatalogItemVariation](entity:CatalogItemVariation)

            for this stock conversion. Selling, receiving or recounting the
            non-stockable `CatalogItemVariation`

            defined with a stock conversion results in adjustments of this
            stockable `CatalogItemVariation`.

            This immutable field must reference a stockable
            `CatalogItemVariation`

            that shares the parent [CatalogItem](entity:CatalogItem) of the
            converted `CatalogItemVariation.`
          minLength: 1
        stockable_quantity:
          type: string
          description: >-
            The quantity of the stockable item variation (as identified by
            `stockable_item_variation_id`)

            equivalent to the non-stockable item variation quantity (as
            specified in `nonstockable_quantity`)

            as defined by this stock conversion.  It accepts a decimal number in
            a string format that can take

            up to 10 digits before the decimal point and up to 5 digits after
            the decimal point.
          minLength: 1
          maxLength: 16
        nonstockable_quantity:
          type: string
          description: >-
            The converted equivalent quantity of the non-stockable
            [CatalogItemVariation](entity:CatalogItemVariation)

            in its measurement unit. The `stockable_quantity` value and this
            `nonstockable_quantity` value together

            define the conversion ratio between stockable item variation and the
            non-stockable item variation.

            It accepts a decimal number in a string format that can take up to
            10 digits before the decimal point

            and up to 5 digits after the decimal point.
          minLength: 1
          maxLength: 16
    CatalogSubscriptionPlan:
      type: object
      description: >-
        Describes a subscription plan. A subscription plan represents what you
        want to sell in a subscription model, and includes references to each of
        the associated subscription plan variations.

        For more information, see [Subscription Plans and
        Variations](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations).
      x-release-status: PUBLIC
      required:
        - name
      properties:
        name:
          type: string
          description: The name of the plan.
        phases:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionPhase'
          description: >-
            A list of SubscriptionPhase containing the
            [SubscriptionPhase](entity:SubscriptionPhase) for this plan.

            This field it required. Not including this field will throw a
            REQUIRED_FIELD_MISSING error
          nullable: true
        subscription_plan_variations:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: The list of subscription plan variations available for this product
          nullable: true
        eligible_item_ids:
          type: array
          items:
            type: string
          description: >-
            The list of IDs of `CatalogItems` that are eligible for subscription
            by this SubscriptionPlan's variations.
          nullable: true
        eligible_category_ids:
          type: array
          items:
            type: string
          description: >-
            The list of IDs of `CatalogCategory` that are eligible for
            subscription by this SubscriptionPlan's variations.
          nullable: true
        all_items:
          type: boolean
          description: >-
            If true, all items in the merchant's catalog are subscribable by
            this SubscriptionPlan.
          nullable: true
    CatalogSubscriptionPlanVariation:
      type: object
      description: >-
        Describes a subscription plan variation. A subscription plan variation
        represents how the subscription for a product or service is sold.

        For more information, see [Subscription Plans and
        Variations](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations).
      x-release-status: PUBLIC
      required:
        - name
        - phases
      properties:
        name:
          type: string
          description: The name of the plan variation.
        phases:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionPhase'
          description: >-
            A list containing each [SubscriptionPhase](entity:SubscriptionPhase)
            for this plan variation.
        subscription_plan_id:
          type: string
          description: The id of the subscription plan, if there is one.
          nullable: true
        monthly_billing_anchor_date:
          type: integer
          description: The day of the month the billing period starts.
          format: int64
          minimum: 1
          maximum: 31
          nullable: true
        can_prorate:
          type: boolean
          description: Whether bills for this plan variation can be split for proration.
          nullable: true
        successor_plan_variation_id:
          type: string
          description: >-
            The ID of a "successor" plan variation to this one. If the field is
            set, and this object is disabled at all

            locations, it indicates that this variation is deprecated and the
            object identified by the successor ID be used in

            its stead.
          nullable: true
    CatalogTax:
      type: object
      description: A tax applicable to an item.
      x-release-status: PUBLIC
      properties:
        name:
          type: string
          description: >-
            The tax's name. This is a searchable attribute for use in applicable
            query filters, and its value length is of Unicode code points.
          maxLength: 255
          nullable: true
        calculation_phase:
          $ref: '#/components/schemas/TaxCalculationPhase'
          description: >-
            Whether the tax is calculated based on a payment's subtotal or
            total.

            See [TaxCalculationPhase](#type-taxcalculationphase) for possible
            values
          nullable: true
        inclusion_type:
          $ref: '#/components/schemas/TaxInclusionType'
          description: |-
            Whether the tax is `ADDITIVE` or `INCLUSIVE`.
            See [TaxInclusionType](#type-taxinclusiontype) for possible values
          nullable: true
        percentage:
          type: string
          description: >-
            The percentage of the tax in decimal form, using a `'.'` as the
            decimal separator and without a `'%'` sign.

            A value of `7.5` corresponds to 7.5%. For a location-specific tax
            rate, contact the tax authority of the location or a tax consultant.
          nullable: true
        applies_to_custom_amounts:
          type: boolean
          description: >-
            If `true`, the fee applies to custom amounts entered into the Square
            Point of Sale

            app that are not associated with a particular `CatalogItem`.
          nullable: true
        enabled:
          type: boolean
          description: >-
            A Boolean flag to indicate whether the tax is displayed as enabled
            (`true`) in the Square Point of Sale app or not (`false`).
          nullable: true
        applies_to_product_set_id:
          type: string
          description: >-
            The ID of a `CatalogProductSet` object. If set, the tax is
            applicable to all products in the product set.
          x-release-status: BETA
          nullable: true
      example:
        object:
          id: '#SalesTax'
          present_at_all_locations: true
          tax_data:
            calculation_phase: TAX_SUBTOTAL_PHASE
            enabled: true
            fee_applies_to_custom_amounts: true
            inclusion_type: ADDITIVE
            name: Sales Tax
            percentage: '5.0'
          type: TAX
    CatalogTimePeriod:
      type: object
      description: Represents a time period - either a single period or a repeating period.
      x-release-status: PUBLIC
      properties:
        event:
          type: string
          description: >-
            An iCalendar (RFC 5545)
            [event](https://tools.ietf.org/html/rfc5545#section-3.6.1), which

            specifies the name, timing, duration and recurrence of this time
            period.


            Example:


            ```

            DTSTART:20190707T180000

            DURATION:P2H

            RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR

            ```


            Only `SUMMARY`, `DTSTART`, `DURATION` and `RRULE` fields are
            supported.

            `DTSTART` must be in local (unzoned) time format. Note that while
            `BEGIN:VEVENT`

            and `END:VEVENT` is not required in the request. The response will
            always

            include them.
          nullable: true
    CatalogV1Id:
      type: object
      description: >-
        A Square API V1 identifier of an item, including the object ID and its
        associated location ID.
      x-release-status: PUBLIC
      properties:
        catalog_v1_id:
          type: string
          description: >-
            The ID for an object used in the Square API V1, if the object ID
            differs from the Square API V2 object ID.
          nullable: true
        location_id:
          type: string
          description: The ID of the `Location` this Connect V1 ID is associated with.
          nullable: true
    CategoryPathToRootNode:
      type: object
      description: A node in the path from a retrieved category to its root node.
      x-release-status: PUBLIC
      properties:
        category_id:
          type: string
          description: The category's ID.
          nullable: true
        category_name:
          type: string
          description: The category's name.
          nullable: true
    ChangeBillingAnchorDateRequest:
      type: object
      description: >-
        Defines input parameters in a request to the

        [ChangeBillingAnchorDate](api-endpoint:Subscriptions-ChangeBillingAnchorDate)
        endpoint.
      x-release-status: BETA
      properties:
        monthly_billing_anchor_date:
          type: integer
          description: The anchor day for the billing cycle.
          minimum: 1
          maximum: 31
          nullable: true
        effective_date:
          type: string
          description: >-
            The `YYYY-MM-DD`-formatted date when the scheduled
            `BILLING_ANCHOR_CHANGE` action takes

            place on the subscription.


            When this date is unspecified or falls within the current billing
            cycle, the billing anchor date

            is changed immediately.
          nullable: true
      example:
        monthly_billing_anchor_date: 1
    ChangeBillingAnchorDateResponse:
      type: object
      description: >-
        Defines output parameters in a request to the

        [ChangeBillingAnchorDate](api-endpoint:Subscriptions-ChangeBillingAnchorDate)
        endpoint.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered during the request.
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: The specified subscription for updating billing anchor date.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionAction'
          description: A list of a single billing anchor date change for the subscription.
      example:
        actions:
          - effective_date: '2023-11-01'
            id: f0a1dfdc-675b-3a14-a640-99f7ac1cee83
            monthly_billing_anchor_date: 1
            type: CHANGE_BILLING_ANCHOR_DATE
        subscription:
          created_at: '2023-06-20T21:53:10Z'
          customer_id: CHFGVKYY8RSV93M5KCYTG4PN0G
          id: 9ba40961-995a-4a3d-8c53-048c40cafc13
          location_id: S8GWD5R9QB376
          monthly_billing_anchor_date: 20
          phases:
            - order_template_id: E6oBY5WfQ2eN4pkYZwq4ka6n7KeZY
              ordinal: 0
              plan_phase_uid: C66BKH3ASTDYGJJCEZXQQSS7
              uid: 98d6f53b-40e1-4714-8827-032fd923be25
          plan_variation_id: FQ7CDXXWSLUJRPM3GFJSJGZ7
          price_override_money:
            amount: 2000
            currency: USD
          source:
            name: My Application
          status: ACTIVE
          timezone: America/Los_Angeles
          version: 3
    ChangeTiming:
      type: string
      enum:
        - IMMEDIATE
        - END_OF_BILLING_CYCLE
      x-enum-elements:
        - name: IMMEDIATE
          description: The action occurs immediately.
        - name: END_OF_BILLING_CYCLE
          description: The action occurs at the end of the billing cycle.
      description: >-
        Supported timings when a pending change, as an action, takes place to a
        subscription.
      x-release-status: BETA
    ChargeRequest:
      type: object
      description: >-
        Defines the parameters that can be included in the body of

        a request to the [Charge](api-endpoint:Transactions-Charge) endpoint.


        Deprecated - recommend using
        [CreatePayment](api-endpoint:Payments-CreatePayment)
      x-release-status: DEPRECATED
      required:
        - idempotency_key
        - amount_money
      properties:
        idempotency_key:
          type: string
          description: >-
            A value you specify that uniquely identifies this

            transaction among transactions you've created.


            If you're unsure whether a particular transaction succeeded,

            you can reattempt it with the same idempotency key without

            worrying about double-charging the buyer.


            See [Idempotency
            keys](https://developer.squareup.com/docs/working-with-apis/idempotency)
            for more information.
          minLength: 1
          maxLength: 192
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money to charge.


            Note that you specify the amount in the

            __smallest denomination of the applicable currency__. For example,
            US dollar

            amounts are specified in cents. See

            [Working with monetary
            amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)
            for details.


            The value of `currency` must match the currency associated with the
            business

            that is charging the card.
        card_nonce:
          type: string
          description: >-
            A payment token generated from the
            [Card.tokenize()](https://developer.squareup.com/reference/sdks/web/payments/objects/Card#Card.tokenize)
            that represents the card

            to charge.


            The application that provides a payment token to this endpoint must
            be the

            _same application_ that generated the payment token with the Web
            Payments SDK.

            Otherwise, the nonce is invalid.


            Do not provide a value for this field if you provide a value for

            `customer_card_id`.
          maxLength: 192
          nullable: true
        customer_card_id:
          type: string
          description: >-
            The ID of the customer card on file to charge. Do

            not provide a value for this field if you provide a value for
            `card_nonce`.


            If you provide this value, you _must_ also provide a value for

            `customer_id`.
          maxLength: 192
          nullable: true
        delay_capture:
          type: boolean
          description: >-
            If `true`, the request will only perform an Auth on the provided

            card. You can then later perform either a Capture (with the

            [CaptureTransaction](api-endpoint:Transactions-CaptureTransaction)
            endpoint) or a Void

            (with the
            [VoidTransaction](api-endpoint:Transactions-VoidTransaction)
            endpoint).


            Default value: `false`
          nullable: true
        reference_id:
          type: string
          description: >-
            An optional ID you can associate with the transaction for your own

            purposes (such as to associate the transaction with an entity ID in
            your

            own database).


            This value cannot exceed 40 characters.
          maxLength: 40
          nullable: true
        note:
          type: string
          description: |-
            An optional note to associate with the transaction.

            This value cannot exceed 60 characters.
          maxLength: 60
          nullable: true
        customer_id:
          type: string
          description: >-
            The ID of the customer to associate this transaction with. This
            field

            is required if you provide a value for `customer_card_id`, and
            optional

            otherwise.
          maxLength: 50
          nullable: true
        billing_address:
          $ref: '#/components/schemas/Address'
          description: >-
            The buyer's billing address. This value is optional, but this
            transaction

            is ineligible for chargeback protection if neither this parameter
            nor

            `shipping_address` is provided.
          nullable: true
        shipping_address:
          $ref: '#/components/schemas/Address'
          description: >-
            The buyer's shipping address, if available. This value is optional,

            but this transaction is ineligible for chargeback protection if
            neither this

            parameter nor `billing_address` is provided.
          nullable: true
        buyer_email_address:
          type: string
          description: >-
            The buyer's email address, if available. This value is optional,

            but this transaction is ineligible for chargeback protection if it
            is not

            provided.
          nullable: true
        order_id:
          type: string
          description: >-
            The ID of the order to associate with this transaction.


            If you provide this value, the `amount_money` value of your request
            must

            __exactly match__ the value of the order's `total_money` field.
          maxLength: 192
          nullable: true
        additional_recipients:
          type: array
          items:
            $ref: '#/components/schemas/ChargeRequestAdditionalRecipient'
          description: >-
            The basic primitive of multi-party transaction. The value is
            optional.

            The transaction facilitated by you can be split from here.


            If you provide this value, the `amount_money` value in your
            additional_recipients

            must not be more than 90% of the `amount_money` value in the charge
            request.

            The `location_id` must be the valid location of the app owner
            merchant.


            This field requires the `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth
            permission.


            This field is currently not supported in sandbox.
          nullable: true
        verification_token:
          type: string
          description: |-
            A token generated by SqPaymentForm's verifyBuyer() that represents
            customer's device info and 3ds challenge result.
          nullable: true
      example:
        additional_recipients:
          - amount_money:
              amount: 20
              currency: USD
            description: Application fees
            location_id: 057P5VYJ4A5X1
        amount_money:
          amount: 200
          currency: USD
        billing_address:
          address_line_1: 500 Electric Ave
          address_line_2: Suite 600
          administrative_district_level_1: NY
          country: US
          locality: New York
          postal_code: '10003'
        card_nonce: card_nonce_from_square_123
        delay_capture: false
        idempotency_key: 74ae1696-b1e3-4328-af6d-f1e04d947a13
        note: some optional note
        reference_id: some optional reference id
        shipping_address:
          address_line_1: 123 Main St
          administrative_district_level_1: CA
          country: US
          locality: San Francisco
          postal_code: '94114'
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/Charge/ChargeRequest.csharp
        java: /sdk_samples/Charge/ChargeRequest.java
        javascript: /sdk_samples/Charge/ChargeRequest.javascript
        php: /sdk_samples/Charge/ChargeRequest.php
        python: /sdk_samples/Charge/ChargeRequest.python
        ruby: /sdk_samples/Charge/ChargeRequest.ruby
    ChargeRequestAdditionalRecipient:
      type: object
      description: >-
        Represents an additional recipient (other than the merchant) entitled to
        a portion of the tender.

        Support is currently limited to USD, CAD and GBP currencies
      x-release-status: DEPRECATED
      required:
        - location_id
        - description
        - amount_money
      properties:
        location_id:
          type: string
          description: >-
            The location ID for a recipient (other than the merchant) receiving
            a portion of the tender.
          minLength: 1
          maxLength: 50
        description:
          type: string
          description: The description of the additional recipient.
          minLength: 1
          maxLength: 100
        amount_money:
          $ref: '#/components/schemas/Money'
          description: The amount of money distributed to the recipient.
    ChargeResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [Charge](api-endpoint:Transactions-Charge) endpoint.


        One of `errors` or `transaction` is present in a given response (never
        both).
      x-release-status: DEPRECATED
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        transaction:
          $ref: '#/components/schemas/Transaction'
          description: The created transaction.
      example:
        transaction:
          created_at: '2016-03-10T22:57:56Z'
          id: KnL67ZIwXCPtzOrqj0HrkxMF
          location_id: 18YC4JDH91E1H
          product: EXTERNAL_API
          reference_id: some optional reference id
          tenders:
            - additional_recipients:
                - amount_money:
                    amount: 20
                    currency: USD
                  description: Application fees
                  location_id: 057P5VYJ4A5X1
                  receivable_id: ISu5xwxJ5v0CMJTQq7RvqyMF
              amount_money:
                amount: 200
                currency: USD
              card_details:
                card:
                  card_brand: VISA
                  last_4: '1111'
                entry_method: KEYED
                status: CAPTURED
              created_at: '2016-03-10T22:57:56Z'
              id: MtZRYYdDrYNQbOvV7nbuBvMF
              location_id: 18YC4JDH91E1H
              note: some optional note
              transaction_id: KnL67ZIwXCPtzOrqj0HrkxMF
              type: CARD
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/Charge/ChargeResponse.csharp
        java: /sdk_samples/Charge/ChargeResponse.java
        javascript: /sdk_samples/Charge/ChargeResponse.javascript
        php: /sdk_samples/Charge/ChargeResponse.php
        python: /sdk_samples/Charge/ChargeResponse.python
        ruby: /sdk_samples/Charge/ChargeResponse.ruby
    Checkout:
      type: object
      description: |-
        Square Checkout lets merchants accept online payments for supported
        payment types using a checkout workflow hosted on squareup.com.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: ID generated by Square Checkout when a new checkout is requested.
        checkout_page_url:
          type: string
          description: |-
            The URL that the buyer's browser should be redirected to after the
            checkout is completed.
          nullable: true
        ask_for_shipping_address:
          type: boolean
          description: >-
            If `true`, Square Checkout will collect shipping information on your

            behalf and store that information with the transaction information
            in your

            Square Dashboard.


            Default: `false`.
          nullable: true
        merchant_support_email:
          type: string
          description: >-
            The email address to display on the Square Checkout confirmation
            page

            and confirmation email that the buyer can use to contact the
            merchant.


            If this value is not set, the confirmation page and email will
            display the

            primary email address associated with the merchant's Square account.


            Default: none; only exists if explicitly set.
          nullable: true
        pre_populate_buyer_email:
          type: string
          description: |-
            If provided, the buyer's email is pre-populated on the checkout page
            as an editable text field.

            Default: none; only exists if explicitly set.
          nullable: true
        pre_populate_shipping_address:
          $ref: '#/components/schemas/Address'
          description: |-
            If provided, the buyer's shipping info is pre-populated on the
            checkout page as editable text fields.

            Default: none; only exists if explicitly set.
          nullable: true
        redirect_url:
          type: string
          description: >-
            The URL to redirect to after checkout is completed with
            `checkoutId`,

            Square's `orderId`, `transactionId`, and `referenceId` appended as
            URL

            parameters. For example, if the provided redirect_url is

            `http://www.example.com/order-complete`, a successful transaction
            redirects

            the customer to:


            <pre><code>http://www.example.com/order-complete?checkoutId=xxxxxx&amp;orderId=xxxxxx&amp;referenceId=xxxxxx&amp;transactionId=xxxxxx</code></pre>


            If you do not provide a redirect URL, Square Checkout will display
            an order

            confirmation page on your behalf; however Square strongly recommends
            that

            you provide a redirect URL so you can verify the transaction results
            and

            finalize the order through your existing/normal confirmation
            workflow.
          nullable: true
        order:
          $ref: '#/components/schemas/Order'
          description: Order to be checked out.
          nullable: true
        created_at:
          type: string
          description: The time when the checkout was created, in RFC 3339 format.
          readOnly: true
        additional_recipients:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalRecipient'
          description: >-
            Additional recipients (other than the merchant) receiving a portion
            of this checkout.

            For example, fees assessed on the purchase by a third party
            integration.
          x-release-status: DEPRECATED
          nullable: true
    CheckoutLocationSettings:
      type: object
      x-release-status: BETA
      properties:
        location_id:
          type: string
          description: The ID of the location that these settings apply to.
          nullable: true
        customer_notes_enabled:
          type: boolean
          description: Indicates whether customers are allowed to leave notes at checkout.
          nullable: true
        policies:
          type: array
          items:
            $ref: '#/components/schemas/CheckoutLocationSettingsPolicy'
          description: |-
            Policy information is displayed at the bottom of the checkout pages.
            You can set a maximum of two policies.
          nullable: true
        branding:
          $ref: '#/components/schemas/CheckoutLocationSettingsBranding'
          description: The branding settings for this location.
          nullable: true
        tipping:
          $ref: '#/components/schemas/CheckoutLocationSettingsTipping'
          description: The tip settings for this location.
          nullable: true
        coupons:
          $ref: '#/components/schemas/CheckoutLocationSettingsCoupons'
          description: The coupon settings for this location.
          nullable: true
        updated_at:
          type: string
          description: >-
            The timestamp when the settings were last updated, in RFC 3339
            format.

            Examples for January 25th, 2020 6:25:34pm Pacific Standard Time:

            UTC: 2020-01-26T02:25:34Z

            Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00
          readOnly: true
    CheckoutLocationSettingsBranding:
      type: object
      x-release-status: BETA
      properties:
        header_type:
          $ref: '#/components/schemas/CheckoutLocationSettingsBrandingHeaderType'
          description: |-
            Show the location logo on the checkout page.
            See [HeaderType](#type-headertype) for possible values
          nullable: true
        button_color:
          type: string
          description: >-
            The HTML-supported hex color for the button on the checkout page
            (for example, "#FFFFFF").
          minLength: 7
          maxLength: 7
          nullable: true
        button_shape:
          $ref: '#/components/schemas/CheckoutLocationSettingsBrandingButtonShape'
          description: |-
            The shape of the button on the checkout page.
            See [ButtonShape](#type-buttonshape) for possible values
          nullable: true
    CheckoutLocationSettingsBrandingButtonShape:
      type: string
      enum:
        - SQUARED
        - ROUNDED
        - PILL
      x-enum-elements:
        - name: SQUARED
          description: ''
        - name: ROUNDED
          description: ''
        - name: PILL
          description: ''
      x-release-status: BETA
    CheckoutLocationSettingsBrandingHeaderType:
      type: string
      enum:
        - BUSINESS_NAME
        - FRAMED_LOGO
        - FULL_WIDTH_LOGO
      x-enum-elements:
        - name: BUSINESS_NAME
          description: ''
        - name: FRAMED_LOGO
          description: ''
        - name: FULL_WIDTH_LOGO
          description: ''
      x-release-status: BETA
    CheckoutLocationSettingsCoupons:
      type: object
      x-release-status: BETA
      properties:
        enabled:
          type: boolean
          description: Indicates whether coupons are enabled for this location.
          nullable: true
    CheckoutLocationSettingsPolicy:
      type: object
      x-release-status: BETA
      properties:
        uid:
          type: string
          description: >-
            A unique ID to identify the policy when making changes. You must set
            the UID for policy updates, but its optional when setting new
            policies.
          nullable: true
        title:
          type: string
          description: >-
            The title of the policy. This is required when setting the
            description, though you can update it in a different request.
          maxLength: 50
          nullable: true
        description:
          type: string
          description: The description of the policy.
          maxLength: 4096
          nullable: true
    CheckoutLocationSettingsTipping:
      type: object
      x-release-status: BETA
      properties:
        percentages:
          type: array
          items:
            type: integer
          description: >-
            Set three custom percentage amounts that buyers can select at
            checkout. If Smart Tip is enabled, this only applies to transactions
            totaling $10 or more.
          nullable: true
        smart_tipping_enabled:
          type: boolean
          description: >-
            Enables Smart Tip Amounts. If Smart Tip Amounts is enabled, tipping
            works as follows:

            If a transaction is less than $10, the available tipping options
            include No Tip, $1, $2, or $3.

            If a transaction is $10 or more, the available tipping options
            include No Tip, 15%, 20%, or 25%. 

            You can set custom percentage amounts with the `percentages` field.
          nullable: true
        default_percent:
          type: integer
          description: >-
            Set the pre-selected percentage amounts that appear at checkout. If
            Smart Tip is enabled, this only applies to transactions totaling $10
            or more.
          nullable: true
        smart_tips:
          type: array
          items:
            $ref: '#/components/schemas/Money'
          description: Show the Smart Tip Amounts for this location.
          nullable: true
        default_smart_tip:
          $ref: '#/components/schemas/Money'
          description: >-
            Set the pre-selected whole amount that appears at checkout when
            Smart Tip is enabled and the transaction amount is less than $10.
          nullable: true
    CheckoutMerchantSettings:
      type: object
      x-release-status: BETA
      properties:
        payment_methods:
          $ref: '#/components/schemas/CheckoutMerchantSettingsPaymentMethods'
          description: The set of payment methods accepted for the merchant's account.
          nullable: true
        updated_at:
          type: string
          description: >-
            The timestamp when the settings were last updated, in RFC 3339
            format.

            Examples for January 25th, 2020 6:25:34pm Pacific Standard Time:

            UTC: 2020-01-26T02:25:34Z

            Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00
          readOnly: true
    CheckoutMerchantSettingsPaymentMethods:
      type: object
      x-release-status: BETA
      properties:
        apple_pay:
          $ref: >-
            #/components/schemas/CheckoutMerchantSettingsPaymentMethodsPaymentMethod
          nullable: true
        google_pay:
          $ref: >-
            #/components/schemas/CheckoutMerchantSettingsPaymentMethodsPaymentMethod
          nullable: true
        cash_app:
          $ref: >-
            #/components/schemas/CheckoutMerchantSettingsPaymentMethodsPaymentMethod
          nullable: true
        afterpay_clearpay:
          $ref: >-
            #/components/schemas/CheckoutMerchantSettingsPaymentMethodsAfterpayClearpay
          nullable: true
    CheckoutMerchantSettingsPaymentMethodsAfterpayClearpay:
      type: object
      description: The settings allowed for AfterpayClearpay.
      x-release-status: BETA
      properties:
        order_eligibility_range:
          $ref: >-
            #/components/schemas/CheckoutMerchantSettingsPaymentMethodsAfterpayClearpayEligibilityRange
          description: >-
            Afterpay is shown as an option for order totals falling within the
            configured range.
          nullable: true
        item_eligibility_range:
          $ref: >-
            #/components/schemas/CheckoutMerchantSettingsPaymentMethodsAfterpayClearpayEligibilityRange
          description: >-
            Afterpay is shown as an option for item totals falling within the
            configured range.
          nullable: true
        enabled:
          type: boolean
          description: Indicates whether the payment method is enabled for the account.
          readOnly: true
    CheckoutMerchantSettingsPaymentMethodsAfterpayClearpayEligibilityRange:
      type: object
      description: A range of purchase price that qualifies.
      x-release-status: BETA
      required:
        - min
        - max
      properties:
        min:
          $ref: '#/components/schemas/Money'
        max:
          $ref: '#/components/schemas/Money'
    CheckoutMerchantSettingsPaymentMethodsPaymentMethod:
      type: object
      description: The settings allowed for a payment method.
      x-release-status: BETA
      properties:
        enabled:
          type: boolean
          description: Indicates whether the payment method is enabled for the account.
          nullable: true
    CheckoutOptions:
      type: object
      x-release-status: PUBLIC
      properties:
        allow_tipping:
          type: boolean
          description: Indicates whether the payment allows tipping.
          nullable: true
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomField'
          description: The custom fields requesting information from the buyer.
          nullable: true
        subscription_plan_id:
          type: string
          description: >-
            The ID of the subscription plan for the buyer to pay and subscribe.

            For more information, see [Subscription Plan
            Checkout](https://developer.squareup.com/docs/checkout-api/subscription-plan-checkout).
          maxLength: 255
          nullable: true
        redirect_url:
          type: string
          description: >-
            The confirmation page URL to redirect the buyer to after Square
            processes the payment.
          maxLength: 2048
          nullable: true
        merchant_support_email:
          type: string
          description: The email address that buyers can use to contact the seller.
          maxLength: 256
          nullable: true
        ask_for_shipping_address:
          type: boolean
          description: Indicates whether to include the address fields in the payment form.
          nullable: true
        accepted_payment_methods:
          $ref: '#/components/schemas/AcceptedPaymentMethods'
          description: The methods allowed for buyers during checkout.
          nullable: true
        app_fee_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money that the developer is taking as a fee for
            facilitating the payment on behalf of the seller.


            The amount cannot be more than 90% of the total amount of the
            payment.


            The amount must be specified in the smallest denomination of the
            applicable currency (for example, US dollar amounts are specified in
            cents). For more information, see [Working with Monetary
            Amounts](https://developer.squareup.com/docs/build-basics/common-data-types/working-with-monetary-amounts).


            The fee currency code must match the currency associated with the
            seller that is accepting the payment. The application must be from a
            developer account in the same country and using the same currency
            code as the seller. For more information about the application fee
            scenario, see [Take Payments and Collect
            Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).


            To set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth
            permission is required. For more information, see
            [Permissions](https://developer.squareup.com/docs/payments-api/collect-fees/additional-considerations#permissions).
          nullable: true
        shipping_fee:
          $ref: '#/components/schemas/ShippingFee'
          description: >-
            The fee associated with shipping to be applied to the `Order` as a
            service charge.
          nullable: true
        enable_coupon:
          type: boolean
          description: >-
            Indicates whether to include the `Add coupon` section for the buyer
            to provide a Square marketing coupon in the payment form.
          nullable: true
        enable_loyalty:
          type: boolean
          description: >-
            Indicates whether to include the `REWARDS` section for the buyer to
            opt in to loyalty, redeem rewards in the payment form, or both.
          nullable: true
    CheckoutOptionsPaymentType:
      type: string
      enum:
        - CARD_PRESENT
        - MANUAL_CARD_ENTRY
        - FELICA_ID
        - FELICA_QUICPAY
        - FELICA_TRANSPORTATION_GROUP
        - FELICA_ALL
        - PAYPAY
        - QR_CODE
      x-enum-elements:
        - name: CARD_PRESENT
          description: Accept credit card or debit card payments via tap, dip or swipe.
        - name: MANUAL_CARD_ENTRY
          description: >-
            Launches the manual credit or debit card entry screen for the buyer
            to complete.
        - name: FELICA_ID
          description: Launches the iD checkout screen for the buyer to complete.
        - name: FELICA_QUICPAY
          description: Launches the QUICPay checkout screen for the buyer to complete.
        - name: FELICA_TRANSPORTATION_GROUP
          description: >-
            Launches the Transportation Group checkout screen for the buyer to
            complete.
        - name: FELICA_ALL
          description: >-
            Launches a checkout screen for the buyer on the Square Terminal that

            allows them to select a specific FeliCa brand or select the check
            balance screen.
        - name: PAYPAY
          description: Replaced by `QR_CODE`.
        - name: QR_CODE
          description: >-
            Launches Square's QR Code checkout screen for the buyer to complete.

            Displays a single code that supports all digital wallets connected
            to the target

            Seller location (e.g. PayPay)
      x-release-status: PUBLIC
    ClearpayDetails:
      type: object
      description: Additional details about Clearpay payments.
      x-release-status: PUBLIC
      properties:
        email_address:
          type: string
          description: Email address on the buyer's Clearpay account.
          maxLength: 255
          nullable: true
    CloneOrderRequest:
      type: object
      description: |-
        Defines the fields that are included in requests to the
        [CloneOrder](api-endpoint:Orders-CloneOrder) endpoint.
      x-release-status: BETA
      required:
        - order_id
      properties:
        order_id:
          type: string
          description: The ID of the order to clone.
        version:
          type: integer
          description: >-
            An optional order version for concurrency protection.


            If a version is provided, it must match the latest stored version of
            the order to clone.

            If a version is not provided, the API clones the latest version.
        idempotency_key:
          type: string
          description: >-
            A value you specify that uniquely identifies this clone request.


            If you are unsure whether a particular order was cloned
            successfully,

            you can reattempt the call with the same idempotency key without

            worrying about creating duplicate cloned orders.

            The originally cloned order is returned.


            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          nullable: true
      example:
        idempotency_key: UNIQUE_STRING
        order_id: ZAISEM52YcpmcWAzERDOyiWS123
        version: 3
    CloneOrderResponse:
      type: object
      description: |-
        Defines the fields that are included in the response body of
        a request to the [CloneOrder](api-endpoint:Orders-CloneOrder) endpoint.
      x-release-status: BETA
      properties:
        order:
          $ref: '#/components/schemas/Order'
          description: The cloned order.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        order:
          created_at: '2020-01-17T20:47:53.293Z'
          discounts:
            - applied_money:
                amount: 30
                currency: USD
              catalog_object_id: DB7L55ZH2BGWI4H23ULIWOQ7
              name: Membership Discount
              percentage: '0.5'
              scope: ORDER
              type: FIXED_PERCENTAGE
              uid: membership-discount
            - applied_money:
                amount: 303
                currency: USD
              name: Labor Day Sale
              percentage: '5'
              scope: ORDER
              type: FIXED_PERCENTAGE
              uid: labor-day-sale
            - amount_money:
                amount: 100
                currency: USD
              applied_money:
                amount: 100
                currency: USD
              name: Sale - $1.00 off
              scope: LINE_ITEM
              type: FIXED_AMOUNT
              uid: one-dollar-off
          id: CAISENgvlJ6jLWAzERDzjyHVybY
          line_items:
            - applied_discounts:
                - applied_money:
                    amount: 8
                    currency: USD
                  discount_uid: membership-discount
                  uid: jWdgP1TpHPFBuVrz81mXVC
                - applied_money:
                    amount: 79
                    currency: USD
                  discount_uid: labor-day-sale
                  uid: jnZOjjVY57eRcQAVgEwFuC
              applied_taxes:
                - applied_money:
                    amount: 136
                    currency: USD
                  tax_uid: state-sales-tax
                  uid: aKG87ArnDpvMLSZJHxWUl
              base_price_money:
                amount: 1599
                currency: USD
              gross_sales_money:
                amount: 1599
                currency: USD
              name: New York Strip Steak
              quantity: '1'
              total_discount_money:
                amount: 87
                currency: USD
              total_money:
                amount: 1648
                currency: USD
              total_service_charge_money:
                amount: 0
                currency: USD
              total_tax_money:
                amount: 136
                currency: USD
              uid: 8uSwfzvUImn3IRrvciqlXC
              variation_total_price_money:
                amount: 1599
                currency: USD
            - applied_discounts:
                - applied_money:
                    amount: 22
                    currency: USD
                  discount_uid: membership-discount
                  uid: nUXvdsIItfKko0dbYtY58C
                - applied_money:
                    amount: 224
                    currency: USD
                  discount_uid: labor-day-sale
                  uid: qSdkOOOernlVQqsJ94SPjB
                - applied_money:
                    amount: 100
                    currency: USD
                  discount_uid: one-dollar-off
                  uid: y7bVl4njrWAnfDwmz19izB
              applied_taxes:
                - applied_money:
                    amount: 374
                    currency: USD
                  tax_uid: state-sales-tax
                  uid: v1dAgrfUVUPTnVTf9sRPz
              base_price_money:
                amount: 2200
                currency: USD
              catalog_object_id: BEMYCSMIJL46OCDV4KYIKXIB
              gross_sales_money:
                amount: 4500
                currency: USD
              modifiers:
                - base_price_money:
                    amount: 50
                    currency: USD
                  catalog_object_id: CHQX7Y4KY6N5KINJKZCFURPZ
                  name: Well
                  total_price_money:
                    amount: 100
                    currency: USD
                  uid: Lo3qMMckDluu9Qsb58d4CC
              name: New York Steak
              quantity: '2'
              total_discount_money:
                amount: 346
                currency: USD
              total_money:
                amount: 4528
                currency: USD
              total_service_charge_money:
                amount: 0
                currency: USD
              total_tax_money:
                amount: 374
                currency: USD
              uid: v8ZuEXpOJpb0bazLuvrLDB
              variation_name: Larger
              variation_total_price_money:
                amount: 4400
                currency: USD
          location_id: 057P5VYJ4A5X1
          net_amounts:
            discount_money:
              amount: 433
              currency: USD
            service_charge_money:
              amount: 0
              currency: USD
            tax_money:
              amount: 510
              currency: USD
            tip_money:
              amount: 0
              currency: USD
            total_money:
              amount: 6176
              currency: USD
          reference_id: my-order-001
          source:
            name: My App
          state: DRAFT
          taxes:
            - applied_money:
                amount: 510
                currency: USD
              name: State Sales Tax
              percentage: '9'
              scope: ORDER
              type: ADDITIVE
              uid: state-sales-tax
          total_discount_money:
            amount: 433
            currency: USD
          total_money:
            amount: 6176
            currency: USD
          total_service_charge_money:
            amount: 0
            currency: USD
          total_tax_money:
            amount: 510
            currency: USD
          total_tip_money:
            amount: 0
            currency: USD
          updated_at: '2020-01-17T20:47:53.293Z'
          version: 1
    CollectedData:
      type: object
      x-release-status: BETA
      properties:
        input_text:
          type: string
          description: The buyer's input text.
          readOnly: true
    CompletePaymentRequest:
      type: object
      description: >-
        Describes a request to complete (capture) a payment using 

        [CompletePayment](api-endpoint:Payments-CompletePayment).


        By default, payments are set to `autocomplete` immediately after they
        are created.

        To complete payments manually, set `autocomplete` to `false`.
      x-release-status: PUBLIC
      properties:
        version_token:
          type: string
          description: >-
            Used for optimistic concurrency. This opaque token identifies the
            current `Payment` 

            version that the caller expects. If the server has a different
            version of the Payment, 

            the update fails and a response with a VERSION_MISMATCH error is
            returned.
          x-release-status: BETA
          nullable: true
      example: {}
    CompletePaymentResponse:
      type: object
      description: >-
        Defines the response returned
        by[CompletePayment](api-endpoint:Payments-CompletePayment).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        payment:
          $ref: '#/components/schemas/Payment'
          description: The successfully completed payment.
      example:
        payment:
          amount_money:
            amount: 555
            currency: USD
          application_details:
            application_id: sq0ids-Pw67AZAlLVB7hsRmwlJPuA
            square_product: VIRTUAL_TERMINAL
          approved_money:
            amount: 555
            currency: USD
          card_details:
            auth_result_code: 2Nkw7q
            avs_status: AVS_ACCEPTED
            card:
              bin: '411111'
              card_brand: VISA
              card_type: DEBIT
              exp_month: 11
              exp_year: 2022
              fingerprint: >-
                sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ
              last_4: '1111'
              prepaid_type: NOT_PREPAID
            card_payment_timeline:
              authorized_at: '2021-10-13T19:34:33.680Z'
              captured_at: '2021-10-13T19:34:34.340Z'
            cvv_status: CVV_ACCEPTED
            entry_method: KEYED
            statement_description: SQ *EXAMPLE TEST GOSQ.C
            status: CAPTURED
          created_at: '2021-10-13T19:34:33.524Z'
          delay_action: CANCEL
          delay_duration: PT168H
          delayed_until: '2021-10-20T19:34:33.524Z'
          employee_id: TMoK_ogh6rH1o4dV
          id: bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY
          location_id: L88917AVBK2S5
          note: Test Note
          order_id: d7eKah653Z579f3gVtjlxpSlmUcZY
          processing_fee:
            - amount_money:
                amount: 34
                currency: USD
              effective_at: '2021-10-13T21:34:35.000Z'
              type: INITIAL
          receipt_number: bP9m
          receipt_url: https://squareup.com/receipt/preview/bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY
          source_type: CARD
          status: COMPLETED
          team_member_id: TMoK_ogh6rH1o4dV
          total_money:
            amount: 555
            currency: USD
          updated_at: '2021-10-13T19:34:34.339Z'
          version_token: 56pRkL3slrzet2iQrTp9n0bdJVYTB9YEWdTNjQfZOPV6o
    Component:
      type: object
      description: The wrapper object for the component entries of a given component type.
      x-release-status: BETA
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/ComponentComponentType'
          description: >-
            The type of this component. Each component type has expected
            properties expressed

            in a structured format within its corresponding `*_details` field.

            See [ComponentType](#type-componenttype) for possible values
        application_details:
          $ref: '#/components/schemas/DeviceComponentDetailsApplicationDetails'
          description: >-
            Structured data for an `Application`, set for Components of type
            `APPLICATION`.
          nullable: true
        card_reader_details:
          $ref: '#/components/schemas/DeviceComponentDetailsCardReaderDetails'
          description: >-
            Structured data for a `CardReader`, set for Components of type
            `CARD_READER`.
          nullable: true
        battery_details:
          $ref: '#/components/schemas/DeviceComponentDetailsBatteryDetails'
          description: >-
            Structured data for a `Battery`, set for Components of type
            `BATTERY`.
          nullable: true
        wifi_details:
          $ref: '#/components/schemas/DeviceComponentDetailsWiFiDetails'
          description: >-
            Structured data for a `WiFi` interface, set for Components of type
            `WIFI`.
          nullable: true
        ethernet_details:
          $ref: '#/components/schemas/DeviceComponentDetailsEthernetDetails'
          description: >-
            Structured data for an `Ethernet` interface, set for Components of
            type `ETHERNET`.
          nullable: true
    ComponentComponentType:
      type: string
      enum:
        - APPLICATION
        - CARD_READER
        - BATTERY
        - WIFI
        - ETHERNET
        - PRINTER
      x-enum-elements:
        - name: APPLICATION
          description: ''
        - name: CARD_READER
          description: ''
        - name: BATTERY
          description: ''
        - name: WIFI
          description: ''
        - name: ETHERNET
          description: ''
        - name: PRINTER
          description: ''
      description: An enum for ComponentType.
      x-release-status: BETA
    ConfirmationDecision:
      type: object
      x-release-status: BETA
      properties:
        has_agreed:
          type: boolean
          description: The buyer's decision to the displayed terms.
          readOnly: true
    ConfirmationOptions:
      type: object
      x-release-status: BETA
      required:
        - title
        - body
        - agree_button_text
      properties:
        title:
          type: string
          description: >-
            The title text to display in the confirmation screen flow on the
            Terminal.
          minLength: 1
          maxLength: 250
        body:
          type: string
          description: >-
            The agreement details to display in the confirmation flow on the
            Terminal.
          minLength: 1
          maxLength: 10000
        agree_button_text:
          type: string
          description: >-
            The button text to display indicating the customer agrees to the
            displayed terms.
          minLength: 1
          maxLength: 250
        disagree_button_text:
          type: string
          description: >-
            The button text to display indicating the customer does not agree to
            the displayed terms.
          minLength: 1
          maxLength: 250
          nullable: true
        decision:
          $ref: '#/components/schemas/ConfirmationDecision'
          description: >-
            The result of the buyers actions when presented with the
            confirmation screen.
          readOnly: true
    Coordinates:
      type: object
      description: Latitude and longitude coordinates.
      x-release-status: PUBLIC
      properties:
        latitude:
          type: number
          description: The latitude of the coordinate expressed in degrees.
          nullable: true
        longitude:
          type: number
          description: The longitude of the coordinate expressed in degrees.
          nullable: true
    Country:
      type: string
      enum:
        - ZZ
        - AD
        - AE
        - AF
        - AG
        - AI
        - AL
        - AM
        - AO
        - AQ
        - AR
        - AS
        - AT
        - AU
        - AW
        - AX
        - AZ
        - BA
        - BB
        - BD
        - BE
        - BF
        - BG
        - BH
        - BI
        - BJ
        - BL
        - BM
        - BN
        - BO
        - BQ
        - BR
        - BS
        - BT
        - BV
        - BW
        - BY
        - BZ
        - CA
        - CC
        - CD
        - CF
        - CG
        - CH
        - CI
        - CK
        - CL
        - CM
        - CN
        - CO
        - CR
        - CU
        - CV
        - CW
        - CX
        - CY
        - CZ
        - DE
        - DJ
        - DK
        - DM
        - DO
        - DZ
        - EC
        - EE
        - EG
        - EH
        - ER
        - ES
        - ET
        - FI
        - FJ
        - FK
        - FM
        - FO
        - FR
        - GA
        - GB
        - GD
        - GE
        - GF
        - GG
        - GH
        - GI
        - GL
        - GM
        - GN
        - GP
        - GQ
        - GR
        - GS
        - GT
        - GU
        - GW
        - GY
        - HK
        - HM
        - HN
        - HR
        - HT
        - HU
        - ID
        - IE
        - IL
        - IM
        - IN
        - IO
        - IQ
        - IR
        - IS
        - IT
        - JE
        - JM
        - JO
        - JP
        - KE
        - KG
        - KH
        - KI
        - KM
        - KN
        - KP
        - KR
        - KW
        - KY
        - KZ
        - LA
        - LB
        - LC
        - LI
        - LK
        - LR
        - LS
        - LT
        - LU
        - LV
        - LY
        - MA
        - MC
        - MD
        - ME
        - MF
        - MG
        - MH
        - MK
        - ML
        - MM
        - MN
        - MO
        - MP
        - MQ
        - MR
        - MS
        - MT
        - MU
        - MV
        - MW
        - MX
        - MY
        - MZ
        - NA
        - NC
        - NE
        - NF
        - NG
        - NI
        - NL
        - 'NO'
        - NP
        - NR
        - NU
        - NZ
        - OM
        - PA
        - PE
        - PF
        - PG
        - PH
        - PK
        - PL
        - PM
        - PN
        - PR
        - PS
        - PT
        - PW
        - PY
        - QA
        - RE
        - RO
        - RS
        - RU
        - RW
        - SA
        - SB
        - SC
        - SD
        - SE
        - SG
        - SH
        - SI
        - SJ
        - SK
        - SL
        - SM
        - SN
        - SO
        - SR
        - SS
        - ST
        - SV
        - SX
        - SY
        - SZ
        - TC
        - TD
        - TF
        - TG
        - TH
        - TJ
        - TK
        - TL
        - TM
        - TN
        - TO
        - TR
        - TT
        - TV
        - TW
        - TZ
        - UA
        - UG
        - UM
        - US
        - UY
        - UZ
        - VA
        - VC
        - VE
        - VG
        - VI
        - VN
        - VU
        - WF
        - WS
        - YE
        - YT
        - ZA
        - ZM
        - ZW
      x-enum-elements:
        - name: ZZ
          description: Unknown
        - name: AD
          description: Andorra
        - name: AE
          description: United Arab Emirates
        - name: AF
          description: Afghanistan
        - name: AG
          description: Antigua and Barbuda
        - name: AI
          description: Anguilla
        - name: AL
          description: Albania
        - name: AM
          description: Armenia
        - name: AO
          description: Angola
        - name: AQ
          description: Antartica
        - name: AR
          description: Argentina
        - name: AS
          description: American Samoa
        - name: AT
          description: Austria
        - name: AU
          description: Australia
        - name: AW
          description: Aruba
        - name: AX
          description: �land Islands
        - name: AZ
          description: Azerbaijan
        - name: BA
          description: Bosnia and Herzegovina
        - name: BB
          description: Barbados
        - name: BD
          description: Bangladesh
        - name: BE
          description: Belgium
        - name: BF
          description: Burkina Faso
        - name: BG
          description: Bulgaria
        - name: BH
          description: Bahrain
        - name: BI
          description: Burundi
        - name: BJ
          description: Benin
        - name: BL
          description: Saint Barth�lemy
        - name: BM
          description: Bermuda
        - name: BN
          description: Brunei
        - name: BO
          description: Bolivia
        - name: BQ
          description: Bonaire
        - name: BR
          description: Brazil
        - name: BS
          description: Bahamas
        - name: BT
          description: Bhutan
        - name: BV
          description: Bouvet Island
        - name: BW
          description: Botswana
        - name: BY
          description: Belarus
        - name: BZ
          description: Belize
        - name: CA
          description: Canada
        - name: CC
          description: Cocos Islands
        - name: CD
          description: Democratic Republic of the Congo
        - name: CF
          description: Central African Republic
        - name: CG
          description: Congo
        - name: CH
          description: Switzerland
        - name: CI
          description: Ivory Coast
        - name: CK
          description: Cook Islands
        - name: CL
          description: Chile
        - name: CM
          description: Cameroon
        - name: CN
          description: China
        - name: CO
          description: Colombia
        - name: CR
          description: Costa Rica
        - name: CU
          description: Cuba
        - name: CV
          description: Cabo Verde
        - name: CW
          description: Cura�ao
        - name: CX
          description: Christmas Island
        - name: CY
          description: Cyprus
        - name: CZ
          description: Czechia
        - name: DE
          description: Germany
        - name: DJ
          description: Djibouti
        - name: DK
          description: Denmark
        - name: DM
          description: Dominica
        - name: DO
          description: Dominican Republic
        - name: DZ
          description: Algeria
        - name: EC
          description: Ecuador
        - name: EE
          description: Estonia
        - name: EG
          description: Egypt
        - name: EH
          description: Western Sahara
        - name: ER
          description: Eritrea
        - name: ES
          description: Spain
        - name: ET
          description: Ethiopia
        - name: FI
          description: Finland
        - name: FJ
          description: Fiji
        - name: FK
          description: Falkland Islands
        - name: FM
          description: Federated States of Micronesia
        - name: FO
          description: Faroe Islands
        - name: FR
          description: France
        - name: GA
          description: Gabon
        - name: GB
          description: United Kingdom
        - name: GD
          description: Grenada
        - name: GE
          description: Georgia
        - name: GF
          description: French Guiana
        - name: GG
          description: Guernsey
        - name: GH
          description: Ghana
        - name: GI
          description: Gibraltar
        - name: GL
          description: Greenland
        - name: GM
          description: Gambia
        - name: GN
          description: Guinea
        - name: GP
          description: Guadeloupe
        - name: GQ
          description: Equatorial Guinea
        - name: GR
          description: Greece
        - name: GS
          description: South Georgia and the South Sandwich Islands
        - name: GT
          description: Guatemala
        - name: GU
          description: Guam
        - name: GW
          description: Guinea-Bissau
        - name: GY
          description: Guyana
        - name: HK
          description: Hong Kong
        - name: HM
          description: Heard Island and McDonald Islands
        - name: HN
          description: Honduras
        - name: HR
          description: Croatia
        - name: HT
          description: Haiti
        - name: HU
          description: Hungary
        - name: ID
          description: Indonesia
        - name: IE
          description: Ireland
        - name: IL
          description: Israel
        - name: IM
          description: Isle of Man
        - name: IN
          description: India
        - name: IO
          description: British Indian Ocean Territory
        - name: IQ
          description: Iraq
        - name: IR
          description: Iran
        - name: IS
          description: Iceland
        - name: IT
          description: Italy
        - name: JE
          description: Jersey
        - name: JM
          description: Jamaica
        - name: JO
          description: Jordan
        - name: JP
          description: Japan
        - name: KE
          description: Kenya
        - name: KG
          description: Kyrgyzstan
        - name: KH
          description: Cambodia
        - name: KI
          description: Kiribati
        - name: KM
          description: Comoros
        - name: KN
          description: Saint Kitts and Nevis
        - name: KP
          description: Democratic People's Republic of Korea
        - name: KR
          description: Republic of Korea
        - name: KW
          description: Kuwait
        - name: KY
          description: Cayman Islands
        - name: KZ
          description: Kazakhstan
        - name: LA
          description: Lao People's Democratic Republic
        - name: LB
          description: Lebanon
        - name: LC
          description: Saint Lucia
        - name: LI
          description: Liechtenstein
        - name: LK
          description: Sri Lanka
        - name: LR
          description: Liberia
        - name: LS
          description: Lesotho
        - name: LT
          description: Lithuania
        - name: LU
          description: Luxembourg
        - name: LV
          description: Latvia
        - name: LY
          description: Libya
        - name: MA
          description: Morocco
        - name: MC
          description: Monaco
        - name: MD
          description: Moldova
        - name: ME
          description: Montenegro
        - name: MF
          description: Saint Martin
        - name: MG
          description: Madagascar
        - name: MH
          description: Marshall Islands
        - name: MK
          description: North Macedonia
        - name: ML
          description: Mali
        - name: MM
          description: Myanmar
        - name: MN
          description: Mongolia
        - name: MO
          description: Macao
        - name: MP
          description: Northern Mariana Islands
        - name: MQ
          description: Martinique
        - name: MR
          description: Mauritania
        - name: MS
          description: Montserrat
        - name: MT
          description: Malta
        - name: MU
          description: Mauritius
        - name: MV
          description: Maldives
        - name: MW
          description: Malawi
        - name: MX
          description: Mexico
        - name: MY
          description: Malaysia
        - name: MZ
          description: Mozambique
        - name: NA
          description: Namibia
        - name: NC
          description: New Caledonia
        - name: NE
          description: Niger
        - name: NF
          description: Norfolk Island
        - name: NG
          description: Nigeria
        - name: NI
          description: Nicaragua
        - name: NL
          description: Netherlands
        - name: 'NO'
          description: Norway
        - name: NP
          description: Nepal
        - name: NR
          description: Nauru
        - name: NU
          description: Niue
        - name: NZ
          description: New Zealand
        - name: OM
          description: Oman
        - name: PA
          description: Panama
        - name: PE
          description: Peru
        - name: PF
          description: French Polynesia
        - name: PG
          description: Papua New Guinea
        - name: PH
          description: Philippines
        - name: PK
          description: Pakistan
        - name: PL
          description: Poland
        - name: PM
          description: Saint Pierre and Miquelon
        - name: PN
          description: Pitcairn
        - name: PR
          description: Puerto Rico
        - name: PS
          description: Palestine
        - name: PT
          description: Portugal
        - name: PW
          description: Palau
        - name: PY
          description: Paraguay
        - name: QA
          description: Qatar
        - name: RE
          description: R�union
        - name: RO
          description: Romania
        - name: RS
          description: Serbia
        - name: RU
          description: Russia
        - name: RW
          description: Rwanda
        - name: SA
          description: Saudi Arabia
        - name: SB
          description: Solomon Islands
        - name: SC
          description: Seychelles
        - name: SD
          description: Sudan
        - name: SE
          description: Sweden
        - name: SG
          description: Singapore
        - name: SH
          description: Saint Helena, Ascension and Tristan da Cunha
        - name: SI
          description: Slovenia
        - name: SJ
          description: Svalbard and Jan Mayen
        - name: SK
          description: Slovakia
        - name: SL
          description: Sierra Leone
        - name: SM
          description: San Marino
        - name: SN
          description: Senegal
        - name: SO
          description: Somalia
        - name: SR
          description: Suriname
        - name: SS
          description: South Sudan
        - name: ST
          description: Sao Tome and Principe
        - name: SV
          description: El Salvador
        - name: SX
          description: Sint Maarten
        - name: SY
          description: Syrian Arab Republic
        - name: SZ
          description: Eswatini
        - name: TC
          description: Turks and Caicos Islands
        - name: TD
          description: Chad
        - name: TF
          description: French Southern Territories
        - name: TG
          description: Togo
        - name: TH
          description: Thailand
        - name: TJ
          description: Tajikistan
        - name: TK
          description: Tokelau
        - name: TL
          description: Timor-Leste
        - name: TM
          description: Turkmenistan
        - name: TN
          description: Tunisia
        - name: TO
          description: Tonga
        - name: TR
          description: Turkey
        - name: TT
          description: Trinidad and Tobago
        - name: TV
          description: Tuvalu
        - name: TW
          description: Taiwan
        - name: TZ
          description: Tanzania
        - name: UA
          description: Ukraine
        - name: UG
          description: Uganda
        - name: UM
          description: United States Minor Outlying Islands
        - name: US
          description: United States of America
        - name: UY
          description: Uruguay
        - name: UZ
          description: Uzbekistan
        - name: VA
          description: Vatican City
        - name: VC
          description: Saint Vincent and the Grenadines
        - name: VE
          description: Venezuela
        - name: VG
          description: British Virgin Islands
        - name: VI
          description: U.S. Virgin Islands
        - name: VN
          description: Vietnam
        - name: VU
          description: Vanuatu
        - name: WF
          description: Wallis and Futuna
        - name: WS
          description: Samoa
        - name: YE
          description: Yemen
        - name: YT
          description: Mayotte
        - name: ZA
          description: South Africa
        - name: ZM
          description: Zambia
        - name: ZW
          description: Zimbabwe
      description: >-
        Indicates the country associated with another entity, such as a
        business.

        Values are in [ISO 3166-1-alpha-2
        format](http://www.iso.org/iso/home/standards/country_codes.htm).
      x-release-status: PUBLIC
    CreateBookingCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents a
        [CreateBookingCustomAttributeDefinition](api-endpoint:BookingCustomAttributes-CreateBookingCustomAttributeDefinition)
        request.
      x-release-status: PUBLIC
      required:
        - custom_attribute_definition
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The custom attribute definition to create, with the following
            fields:


            - `key`


            - `name`. If provided, `name` must be unique (case-sensitive) across
            all visible booking-related custom attribute

            definitions for the seller.


            - `description`


            - `visibility`. Note that all custom attributes are visible in
            exported booking data, including those set to

            `VISIBILITY_HIDDEN`.


            - `schema`. With the exception of the `Selection` data type, the
            `schema` is specified as a

            simple URL to the JSON schema definition hosted on the Square CDN.
            For more information, see

            [Specifying the
            schema](https://developer.squareup.com/docs/booking-custom-attributes-api/custom-attribute-definitions#specify-schema).
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency.
            For more information,

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
    CreateBookingCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a
        [CreateBookingCustomAttributeDefinition](api-endpoint:BookingCustomAttributes-CreateBookingCustomAttributeDefinition)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: PUBLIC
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The newly created custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2022-11-16T15:27:30Z'
          description: The favorite shampoo of the customer.
          key: favoriteShampoo
          name: Favorite Shampoo
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          updated_at: '2022-11-16T15:27:30Z'
          version: 1
          visibility: VISIBILITY_HIDDEN
        errors: []
    CreateBookingRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - booking
      properties:
        idempotency_key:
          type: string
          description: A unique key to make this request an idempotent operation.
          maxLength: 255
        booking:
          $ref: '#/components/schemas/Booking'
          description: The details of the booking to be created.
    CreateBookingResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        booking:
          $ref: '#/components/schemas/Booking'
          description: The booking that was created.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
      example:
        booking:
          appointment_segments:
            - duration_minutes: 60
              service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
              service_variation_version: 1599775456731
              team_member_id: TMXUrsBWWcHTt79t
          created_at: '2020-10-28T15:47:41Z'
          customer_id: EX2QSVGTZN4K1E5QE1CBFNVQ8M
          customer_note: ''
          id: zkras0xv0xwswx
          location_id: LEQHH0YY8B42M
          seller_note: ''
          start_at: '2020-11-26T13:00:00Z'
          status: ACCEPTED
          updated_at: '2020-10-28T15:47:41Z'
          version: 0
        errors: []
    CreateBreakTypeRequest:
      type: object
      description: A request to create a new `BreakType`.
      x-release-status: PUBLIC
      required:
        - break_type
      properties:
        idempotency_key:
          type: string
          description: A unique string value to ensure the idempotency of the operation.
          maxLength: 128
        break_type:
          $ref: '#/components/schemas/BreakType'
          description: The `BreakType` to be created.
      example:
        break_type:
          break_name: Lunch Break
          expected_duration: PT30M
          is_paid: true
          location_id: CGJN03P1D08GF
        idempotency_key: PAD3NG5KSN2GL
    CreateBreakTypeResponse:
      type: object
      description: >-
        The response to the request to create a `BreakType`. The response
        contains

        the created `BreakType` object and might contain a set of `Error`
        objects if

        the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        break_type:
          $ref: '#/components/schemas/BreakType'
          description: The `BreakType` that was created by the request.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        break_type:
          break_name: Lunch Break
          created_at: '2019-02-26T22:42:54Z'
          expected_duration: PT30M
          id: 49SSVDJG76WF3
          is_paid: true
          location_id: CGJN03P1D08GF
          updated_at: '2019-02-26T22:42:54Z'
          version: 1
    CreateCardRequest:
      type: object
      description: >-
        Creates a card from the source (payment token or payment id). Accessible
        via

        HTTP requests at POST https://connect.squareup.com/v2/cards
      x-release-status: PUBLIC
      required:
        - idempotency_key
        - source_id
        - card
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this CreateCard request. Keys can be

            any valid string and must be unique for every request.


            Max: 45 characters


            See [Idempotency
            keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
            for more information.
          minLength: 1
        source_id:
          type: string
          description: >-
            The ID of the source which represents the card information to be
            stored. This can be a card nonce or a payment id.
          minLength: 1
          maxLength: 16384
        verification_token:
          type: string
          description: >-
            An identifying token generated by
            [Payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer).

            Verification tokens encapsulate customer device information and 3-D
            Secure

            challenge results to indicate that Square has verified the buyer
            identity.


            See the [SCA
            Overview](https://developer.squareup.com/docs/sca-overview).
        card:
          $ref: '#/components/schemas/Card'
          description: Payment details associated with the card to be stored.
      example:
        card:
          billing_address:
            address_line_1: 500 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          cardholder_name: Amelia Earhart
          customer_id: VDKXEEKPJN48QDG3BGGFAK05P8
          reference_id: user-id-1
        idempotency_key: 4935a656-a929-4792-b97c-8848be85c27c
        source_id: cnon:uIbfJXhXETSP197M3GB
    CreateCardResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [CreateCard](api-endpoint:Cards-CreateCard) endpoint.


        Note: if there are errors processing the request, the card field will
        not be

        present.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors resulting from the request.
        card:
          $ref: '#/components/schemas/Card'
          description: The card created by the request.
      example:
        card:
          billing_address:
            address_line_1: 500 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          bin: '411111'
          card_brand: VISA
          card_type: CREDIT
          cardholder_name: Amelia Earhart
          customer_id: VDKXEEKPJN48QDG3BGGFAK05P8
          enabled: true
          exp_month: 11
          exp_year: 2022
          fingerprint: >-
            ex-p-cs80EK9Flz7LsCMv-szbptQ_ssAGrhemzSTsPFgt9nzyE6t7okiLIQc-qw_quqKX4Q
          id: ccof:uIbfJXhXETSP197M3GB
          last_4: '1111'
          merchant_id: 6SSW7HV8K2ST5
          prepaid_type: NOT_PREPAID
          reference_id: user-id-1
          version: 1
    CreateCatalogImageRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - idempotency_key
        - image
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this CreateCatalogImage request.

            Keys can be any valid string but must be unique for every
            CreateCatalogImage request.


            See [Idempotency
            keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
            for more information.
          minLength: 1
          maxLength: 128
        object_id:
          type: string
          description: >-
            Unique ID of the `CatalogObject` to attach this `CatalogImage`
            object to. Leave this

            field empty to create unattached images, for example if you are
            building an integration

            where an image can be attached to catalog items at a later time.
        image:
          $ref: '#/components/schemas/CatalogObject'
          description: >-
            The new `CatalogObject` of the `IMAGE` type, namely, a
            `CatalogImage` object, to encapsulate the specified image file.
        is_primary:
          type: boolean
          description: >-
            If this is set to `true`, the image created will be the primary, or
            first image of the object referenced by `object_id`.

            If the `CatalogObject` already has a primary `CatalogImage`, setting
            this field to `true` will replace the primary image.

            If this is set to `false` and you use the Square API version
            2021-12-15 or later, the image id will be appended to the list of
            `image_ids` on the object.


            With Square API version 2021-12-15 or later, the default value is
            `false`. Otherwise, the effective default value is `true`.
          x-release-status: BETA
      example:
        idempotency_key: 528dea59-7bfb-43c1-bd48-4a6bba7dd61f86
        image:
          id: '#TEMP_ID'
          image_data:
            caption: A picture of a cup of coffee
          type: IMAGE
        object_id: ND6EA5AAJEO5WL3JNNIAQA32
    CreateCatalogImageResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        image:
          $ref: '#/components/schemas/CatalogObject'
          description: |-
            The newly created `CatalogImage` including a Square-generated
            URL for the encapsulated image file.
      example:
        image:
          id: KQLFFHA6K6J3YQAQAWDQAL57
          image_data:
            caption: A picture of a cup of coffee
            url: https://...
          type: IMAGE
    CreateCheckoutRequest:
      type: object
      description: |-
        Defines the parameters that can be included in the body of
        a request to the `CreateCheckout` endpoint.
      x-release-status: PUBLIC
      required:
        - idempotency_key
        - order
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this checkout among others you have
            created. It can be

            any valid string but must be unique for every order sent to Square
            Checkout for a given location ID.


            The idempotency key is used to avoid processing the same order more
            than once. If you are 

            unsure whether a particular checkout was created successfully, you
            can attempt it again with

            the same idempotency key and all the same other parameters without
            worrying about creating duplicates.


            You should use a random number/string generator native to the
            language

            you are working in to generate strings for your idempotency keys.


            For more information, see
            [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).
          minLength: 1
          maxLength: 192
        order:
          $ref: '#/components/schemas/CreateOrderRequest'
          description: The order including line items to be checked out.
        ask_for_shipping_address:
          type: boolean
          description: >-
            If `true`, Square Checkout collects shipping information on your
            behalf and stores 

            that information with the transaction information in the Square
            Seller Dashboard.


            Default: `false`.
        merchant_support_email:
          type: string
          description: >-
            The email address to display on the Square Checkout confirmation
            page

            and confirmation email that the buyer can use to contact the seller.


            If this value is not set, the confirmation page and email display
            the

            primary email address associated with the seller's Square account.


            Default: none; only exists if explicitly set.
          maxLength: 254
        pre_populate_buyer_email:
          type: string
          description: |-
            If provided, the buyer's email is prepopulated on the checkout page
            as an editable text field.

            Default: none; only exists if explicitly set.
          maxLength: 254
        pre_populate_shipping_address:
          $ref: '#/components/schemas/Address'
          description: |-
            If provided, the buyer's shipping information is prepopulated on the
            checkout page as editable text fields.

            Default: none; only exists if explicitly set.
        redirect_url:
          type: string
          description: >-
            The URL to redirect to after the checkout is completed with
            `checkoutId`,

            `transactionId`, and `referenceId` appended as URL parameters. For
            example,

            if the provided redirect URL is
            `http://www.example.com/order-complete`, a

            successful transaction redirects the customer to:


            `http://www.example.com/order-complete?checkoutId=xxxxxx&amp;referenceId=xxxxxx&amp;transactionId=xxxxxx`


            If you do not provide a redirect URL, Square Checkout displays an
            order

            confirmation page on your behalf; however, it is strongly
            recommended that

            you provide a redirect URL so you can verify the transaction results
            and

            finalize the order through your existing/normal confirmation
            workflow.


            Default: none; only exists if explicitly set.
          maxLength: 800
        additional_recipients:
          type: array
          items:
            $ref: '#/components/schemas/ChargeRequestAdditionalRecipient'
          description: >-
            The basic primitive of a multi-party transaction. The value is
            optional.

            The transaction facilitated by you can be split from here.


            If you provide this value, the `amount_money` value in your
            `additional_recipients` field

            cannot be more than 90% of the `total_money` calculated by Square
            for your order.

            The `location_id` must be a valid seller location where the checkout
            is occurring.


            This field requires `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth
            permission.


            This field is currently not supported in the Square Sandbox.
        note:
          type: string
          description: |-
            An optional note to associate with the `checkout` object.

            This value cannot exceed 60 characters.
          maxLength: 60
      example:
        additional_recipients:
          - amount_money:
              amount: 60
              currency: USD
            description: Application fees
            location_id: 057P5VYJ4A5X1
        ask_for_shipping_address: true
        idempotency_key: 86ae1696-b1e3-4328-af6d-f1e04d947ad6
        merchant_support_email: merchant+support@website.com
        order:
          idempotency_key: 12ae1696-z1e3-4328-af6d-f1e04d947gd4
          order:
            customer_id: customer_id
            discounts:
              - amount_money:
                  amount: 100
                  currency: USD
                scope: LINE_ITEM
                type: FIXED_AMOUNT
                uid: 56ae1696-z1e3-9328-af6d-f1e04d947gd4
            line_items:
              - applied_discounts:
                  - discount_uid: 56ae1696-z1e3-9328-af6d-f1e04d947gd4
                applied_taxes:
                  - tax_uid: 38ze1696-z1e3-5628-af6d-f1e04d947fg3
                base_price_money:
                  amount: 1500
                  currency: USD
                name: Printed T Shirt
                quantity: '2'
              - base_price_money:
                  amount: 2500
                  currency: USD
                name: Slim Jeans
                quantity: '1'
              - base_price_money:
                  amount: 3500
                  currency: USD
                name: Woven Sweater
                quantity: '3'
            location_id: location_id
            reference_id: reference_id
            taxes:
              - percentage: '7.75'
                scope: LINE_ITEM
                type: INCLUSIVE
                uid: 38ze1696-z1e3-5628-af6d-f1e04d947fg3
        pre_populate_buyer_email: example@email.com
        pre_populate_shipping_address:
          address_line_1: 1455 Market St.
          address_line_2: Suite 600
          administrative_district_level_1: CA
          country: US
          first_name: Jane
          last_name: Doe
          locality: San Francisco
          postal_code: '94103'
        redirect_url: https://merchant.website.com/order-confirm
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/CreateCheckout/CreateCheckoutRequest.csharp
        java: /sdk_samples/CreateCheckout/CreateCheckoutRequest.java
        javascript: /sdk_samples/CreateCheckout/CreateCheckoutRequest.javascript
        php: /sdk_samples/CreateCheckout/CreateCheckoutRequest.php
        python: /sdk_samples/CreateCheckout/CreateCheckoutRequest.python
        ruby: /sdk_samples/CreateCheckout/CreateCheckoutRequest.ruby
    CreateCheckoutResponse:
      type: object
      description: |-
        Defines the fields that are included in the response body of
        a request to the `CreateCheckout` endpoint.
      x-release-status: PUBLIC
      properties:
        checkout:
          $ref: '#/components/schemas/Checkout'
          description: >-
            The newly created `checkout` object associated with the provided
            idempotency key.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        checkout:
          additional_recipients:
            - amount_money:
                amount: 60
                currency: USD
              description: Application fees
              location_id: 057P5VYJ4A5X1
          ask_for_shipping_address: true
          checkout_page_url: >-
            https://connect.squareup.com/v2/checkout?c=CAISEHGimXh-C3RIT4og1a6u1qw&l=CYTKRM7R7JMV8
          created_at: '2017-06-16T22:25:35Z'
          id: CAISEHGimXh-C3RIT4og1a6u1qw
          merchant_support_email: merchant+support@website.com
          order:
            customer_id: customer_id
            discounts:
              - amount_money:
                  amount: 100
                  currency: USD
                applied_money:
                  amount: 100
                  currency: USD
                scope: LINE_ITEM
                type: FIXED_AMOUNT
                uid: 56ae1696-z1e3-9328-af6d-f1e04d947gd4
            line_items:
              - applied_discounts:
                  - applied_money:
                      amount: 100
                      currency: USD
                    discount_uid: 56ae1696-z1e3-9328-af6d-f1e04d947gd4
                applied_taxes:
                  - applied_money:
                      amount: 103
                      currency: USD
                    tax_uid: 38ze1696-z1e3-5628-af6d-f1e04d947fg3
                base_price_money:
                  amount: 1500
                  currency: USD
                name: Printed T Shirt
                quantity: '2'
                total_discount_money:
                  amount: 100
                  currency: USD
                total_money:
                  amount: 1503
                  currency: USD
                total_tax_money:
                  amount: 103
                  currency: USD
              - base_price_money:
                  amount: 2500
                  currency: USD
                name: Slim Jeans
                quantity: '1'
                total_money:
                  amount: 2500
                  currency: USD
              - base_price_money:
                  amount: 3500
                  currency: USD
                name: Woven Sweater
                quantity: '3'
                total_money:
                  amount: 10500
                  currency: USD
            location_id: location_id
            reference_id: reference_id
            taxes:
              - percentage: '7.75'
                scope: LINE_ITEM
                type: INCLUSIVE
                uid: 38ze1696-z1e3-5628-af6d-f1e04d947fg3
            total_discount_money:
              amount: 100
              currency: USD
            total_money:
              amount: 14503
              currency: USD
            total_tax_money:
              amount: 103
              currency: USD
          pre_populate_buyer_email: example@email.com
          pre_populate_shipping_address:
            address_line_1: 1455 Market St.
            address_line_2: Suite 600
            administrative_district_level_1: CA
            country: US
            first_name: Jane
            last_name: Doe
            locality: San Francisco
            postal_code: '94103'
          redirect_url: https://merchant.website.com/order-confirm
          version: 1
    CreateCustomerCardRequest:
      type: object
      description: |-
        Defines the fields that are included in the request body of a request
        to the `CreateCustomerCard` endpoint.
      x-release-status: DEPRECATED
      required:
        - card_nonce
      properties:
        card_nonce:
          type: string
          description: >-
            A card nonce representing the credit card to link to the customer.


            Card nonces are generated by the Square payment form when customers
            enter

            their card information. For more information, see

            [Walkthrough: Integrate Square Payments in a
            Website](https://developer.squareup.com/docs/web-payments/take-card-payment).


            __NOTE:__ Card nonces generated by digital wallets (such as Apple
            Pay)

            cannot be used to create a customer card.
        billing_address:
          $ref: '#/components/schemas/Address'
          description: |-
            Address information for the card on file.

            __NOTE:__ If a billing address is provided in the request, the
            `CreateCustomerCardRequest.billing_address.postal_code` must match
            the postal code encoded in the card nonce.
        cardholder_name:
          type: string
          description: The full name printed on the credit card.
        verification_token:
          type: string
          description: >-
            An identifying token generated by
            [Payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer).

            Verification tokens encapsulate customer device information and 3-D
            Secure

            challenge results to indicate that Square has verified the buyer
            identity.
      example:
        billing_address:
          address_line_1: 500 Electric Ave
          address_line_2: Suite 600
          administrative_district_level_1: NY
          country: US
          locality: New York
          postal_code: '10003'
        card_nonce: YOUR_CARD_NONCE
        cardholder_name: Amelia Earhart
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/CreateCustomerCard/CreateCustomerCardRequest.csharp
        java: /sdk_samples/CreateCustomerCard/CreateCustomerCardRequest.java
        javascript: /sdk_samples/CreateCustomerCard/CreateCustomerCardRequest.javascript
        php: /sdk_samples/CreateCustomerCard/CreateCustomerCardRequest.php
        python: /sdk_samples/CreateCustomerCard/CreateCustomerCardRequest.python
        ruby: /sdk_samples/CreateCustomerCard/CreateCustomerCardRequest.ruby
    CreateCustomerCardResponse:
      type: object
      description: |-
        Defines the fields that are included in the response body of
        a request to the `CreateCustomerCard` endpoint.

        Either `errors` or `card` is present in a given response (never both).
      x-release-status: DEPRECATED
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        card:
          $ref: '#/components/schemas/Card'
          description: The created card on file.
      example:
        card:
          billing_address:
            address_line_1: 500 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          card_brand: VISA
          cardholder_name: Amelia Earhart
          exp_month: 11
          exp_year: 2018
          id: icard-card_id
          last_4: '1111'
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/CreateCustomerCard/CreateCustomerCardResponse.csharp
        java: /sdk_samples/CreateCustomerCard/CreateCustomerCardResponse.java
        javascript: /sdk_samples/CreateCustomerCard/CreateCustomerCardResponse.javascript
        php: /sdk_samples/CreateCustomerCard/CreateCustomerCardResponse.php
        python: /sdk_samples/CreateCustomerCard/CreateCustomerCardResponse.python
        ruby: /sdk_samples/CreateCustomerCard/CreateCustomerCardResponse.ruby
    CreateCustomerCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents a
        [CreateCustomerCustomAttributeDefinition](api-endpoint:CustomerCustomAttributes-CreateCustomerCustomAttributeDefinition)
        request.
      x-release-status: PUBLIC
      required:
        - custom_attribute_definition
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The custom attribute definition to create. Note the following:

            - With the exception of the `Selection` data type, the `schema` is
            specified as a simple URL to the JSON schema

            definition hosted on the Square CDN. For more information, including
            supported values and constraints, see

            [Specifying the
            schema](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attribute-definitions#specify-schema).

            - If provided, `name` must be unique (case-sensitive) across all
            visible customer-related custom attribute definitions for the
            seller.

            - All custom attributes are visible in exported customer data,
            including those set to `VISIBILITY_HIDDEN`.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency.
            For more information,

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
      example:
        custom_attribute_definition:
          description: The favorite movie of the customer.
          key: favoritemovie
          name: Favorite Movie
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          visibility: VISIBILITY_HIDDEN
    CreateCustomerCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a
        [CreateCustomerCustomAttributeDefinition](api-endpoint:CustomerCustomAttributes-CreateCustomerCustomAttributeDefinition)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: PUBLIC
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The new custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2022-04-26T15:27:30Z'
          description: The favorite movie of the customer.
          key: favoritemovie
          name: Favorite Movie
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          updated_at: '2022-04-26T15:27:30Z'
          version: 1
          visibility: VISIBILITY_HIDDEN
    CreateCustomerGroupRequest:
      type: object
      description: >-
        Defines the body parameters that can be included in a request to the

        [CreateCustomerGroup](api-endpoint:CustomerGroups-CreateCustomerGroup)
        endpoint.
      x-release-status: PUBLIC
      required:
        - group
      properties:
        idempotency_key:
          type: string
          description: >-
            The idempotency key for the request. For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
        group:
          $ref: '#/components/schemas/CustomerGroup'
          description: The customer group to create.
      example:
        group:
          name: Loyal Customers
    CreateCustomerGroupResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [CreateCustomerGroup](api-endpoint:CustomerGroups-CreateCustomerGroup)
        endpoint.


        Either `errors` or `group` is present in a given response (never both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        group:
          $ref: '#/components/schemas/CustomerGroup'
          description: The successfully created customer group.
      example:
        group:
          created_at: '2020-04-13T21:54:57.863Z'
          id: 2TAT3CMH4Q0A9M87XJZED0WMR3
          name: Loyal Customers
          updated_at: '2020-04-13T21:54:58Z'
    CreateCustomerRequest:
      type: object
      description: |-
        Defines the body parameters that can be included in a request to the
        `CreateCustomer` endpoint.
      x-release-status: PUBLIC
      properties:
        idempotency_key:
          type: string
          description: "The idempotency key for the request.\tFor more information, see\n[Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)."
        given_name:
          type: string
          description: >-
            The given name (that is, the first name) associated with the
            customer profile.


            The maximum length for this value is 300 characters.
        family_name:
          type: string
          description: >-
            The family name (that is, the last name) associated with the
            customer profile.


            The maximum length for this value is 300 characters.
        company_name:
          type: string
          description: |-
            A business name associated with the customer profile.

            The maximum length for this value is 500 characters.
        nickname:
          type: string
          description: |-
            A nickname for the customer profile.

            The maximum length for this value is 100 characters.
        email_address:
          type: string
          description: |-
            The email address associated with the customer profile.

            The maximum length for this value is 254 characters.
        address:
          $ref: '#/components/schemas/Address'
          description: >-
            The physical address associated with the customer profile. For
            maximum length constraints, see 

            [Customer
            addresses](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#address).

            The `first_name` and `last_name` fields are ignored if they are
            present in the request.
        phone_number:
          type: string
          description: >-
            The phone number associated with the customer profile. The phone
            number must be valid and can contain

            916 digits, with an optional `+` prefix and country code. For more
            information, see

            [Customer phone
            numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number).
        reference_id:
          type: string
          description: |-
            An optional second ID used to associate the customer profile with an
            entity in another system.

            The maximum length for this value is 100 characters.
        note:
          type: string
          description: A custom note associated with the customer profile.
        birthday:
          type: string
          description: >-
            The birthday associated with the customer profile, in `YYYY-MM-DD`
            or `MM-DD` format. For example,

            specify `1998-09-21` for September 21, 1998, or `09-21` for
            September 21. Birthdays are returned in `YYYY-MM-DD`

            format, where `YYYY` is the specified birth year or `0000` if a
            birth year is not specified.
        tax_ids:
          $ref: '#/components/schemas/CustomerTaxIds'
          description: >-
            The tax ID associated with the customer profile. This field is
            available only for customers of sellers

            in EU countries or the United Kingdom. For more information,

            see [Customer tax
            IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids).
      example:
        address:
          address_line_1: 500 Electric Ave
          address_line_2: Suite 600
          administrative_district_level_1: NY
          country: US
          locality: New York
          postal_code: '10003'
        email_address: Amelia.Earhart@example.com
        family_name: Earhart
        given_name: Amelia
        note: a customer
        phone_number: +1-212-555-4240
        reference_id: YOUR_REFERENCE_ID
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/CreateCustomer/CreateCustomerRequest.csharp
        java: /sdk_samples/CreateCustomer/CreateCustomerRequest.java
        javascript: /sdk_samples/CreateCustomer/CreateCustomerRequest.javascript
        php: /sdk_samples/CreateCustomer/CreateCustomerRequest.php
        python: /sdk_samples/CreateCustomer/CreateCustomerRequest.python
        ruby: /sdk_samples/CreateCustomer/CreateCustomerRequest.ruby
    CreateCustomerResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [CreateCustomer](api-endpoint:Customers-CreateCustomer)
        or

        [BulkCreateCustomers](api-endpoint:Customers-BulkCreateCustomers)
        endpoint.


        Either `errors` or `customer` is present in a given response (never
        both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        customer:
          $ref: '#/components/schemas/Customer'
          description: The created customer.
      example:
        customer:
          address:
            address_line_1: 500 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          created_at: '2016-03-23T20:21:54.859Z'
          creation_source: THIRD_PARTY
          email_address: Amelia.Earhart@example.com
          family_name: Earhart
          given_name: Amelia
          id: JDKYHBWT1D4F8MFH63DBMEN8Y4
          note: a customer
          phone_number: +1-212-555-4240
          preferences:
            email_unsubscribed: false
          reference_id: YOUR_REFERENCE_ID
          updated_at: '2016-03-23T20:21:54.859Z'
          version: 0
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/CreateCustomer/CreateCustomerResponse.csharp
        java: /sdk_samples/CreateCustomer/CreateCustomerResponse.java
        javascript: /sdk_samples/CreateCustomer/CreateCustomerResponse.javascript
        php: /sdk_samples/CreateCustomer/CreateCustomerResponse.php
        python: /sdk_samples/CreateCustomer/CreateCustomerResponse.python
        ruby: /sdk_samples/CreateCustomer/CreateCustomerResponse.ruby
    CreateDeviceCodeRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - idempotency_key
        - device_code
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this CreateDeviceCode request. Keys
            can

            be any valid string but must be unique for every CreateDeviceCode
            request.


            See [Idempotency
            keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
            for more information.
          minLength: 1
          maxLength: 128
        device_code:
          $ref: '#/components/schemas/DeviceCode'
          description: The device code to create.
      example:
        device_code:
          location_id: B5E4484SHHNYH
          name: Counter 1
          product_type: TERMINAL_API
        idempotency_key: 01bb00a6-0c86-4770-94ed-f5fca973cd56
    CreateDeviceCodeResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        device_code:
          $ref: '#/components/schemas/DeviceCode'
          description: The created DeviceCode object containing the device code string.
      example:
        device_code:
          code: EBCARJ
          created_at: '2020-02-06T18:44:33.000Z'
          id: B3Z6NAMYQSMTM
          location_id: B5E4484SHHNYH
          name: Counter 1
          pair_by: '2020-02-06T18:49:33.000Z'
          product_type: TERMINAL_API
          status: UNPAIRED
          status_changed_at: '2020-02-06T18:44:33.000Z'
    CreateDisputeEvidenceFileRequest:
      type: object
      description: Defines the parameters for a `CreateDisputeEvidenceFile` request.
      x-release-status: PUBLIC
      required:
        - idempotency_key
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique key identifying the request. For more information, see
            [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).
          minLength: 1
          maxLength: 45
        evidence_type:
          $ref: '#/components/schemas/DisputeEvidenceType'
          description: >-
            The type of evidence you are uploading.

            See [DisputeEvidenceType](#type-disputeevidencetype) for possible
            values
        content_type:
          type: string
          description: >-
            The MIME type of the uploaded file.

            The type can be image/heic, image/heif, image/jpeg, application/pdf,
            image/png, or image/tiff.
          minLength: 1
          maxLength: 40
    CreateDisputeEvidenceFileResponse:
      type: object
      description: Defines the fields in a `CreateDisputeEvidenceFile` response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        evidence:
          $ref: '#/components/schemas/DisputeEvidence'
          description: The metadata of the newly uploaded dispute evidence.
      example:
        evidence:
          dispute_id: bVTprrwk0gygTLZ96VX1oB
          evidence_file:
            filename: customer-interaction.jpg
            filetype: image/jpeg
          id: TOomLInj6iWmP3N8qfCXrB
          uploaded_at: '2022-05-18T16:01:10.000Z'
    CreateDisputeEvidenceTextRequest:
      type: object
      description: Defines the parameters for a `CreateDisputeEvidenceText` request.
      x-release-status: PUBLIC
      required:
        - idempotency_key
        - evidence_text
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique key identifying the request. For more information, see
            [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).
          minLength: 1
          maxLength: 45
        evidence_type:
          $ref: '#/components/schemas/DisputeEvidenceType'
          description: >-
            The type of evidence you are uploading.

            See [DisputeEvidenceType](#type-disputeevidencetype) for possible
            values
        evidence_text:
          type: string
          description: The evidence string.
          minLength: 1
          maxLength: 500
      example:
        evidence_text: 1Z8888888888888888
        evidence_type: TRACKING_NUMBER
        idempotency_key: ed3ee3933d946f1514d505d173c82648
    CreateDisputeEvidenceTextResponse:
      type: object
      description: Defines the fields in a `CreateDisputeEvidenceText` response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        evidence:
          $ref: '#/components/schemas/DisputeEvidence'
          description: The newly uploaded dispute evidence metadata.
      example:
        evidence:
          dispute_id: bVTprrwk0gygTLZ96VX1oB
          evidence_text: The customer purchased the item twice, on April 11 and April 28.
          evidence_type: REBUTTAL_EXPLANATION
          id: TOomLInj6iWmP3N8qfCXrB
          uploaded_at: '2022-05-18T16:01:10.000Z'
    CreateGiftCardActivityRequest:
      type: object
      description: A request to create a gift card activity.
      x-release-status: PUBLIC
      required:
        - idempotency_key
        - gift_card_activity
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies the `CreateGiftCardActivity`
            request.
          minLength: 1
          maxLength: 128
        gift_card_activity:
          $ref: '#/components/schemas/GiftCardActivity'
          description: >-
            The activity to create for the gift card. This activity must specify
            `gift_card_id` or `gift_card_gan` for the target

            gift card, the `location_id` where the activity occurred, and the
            activity `type` along with the corresponding activity details.
      example:
        gift_card_activity:
          activate_activity_details:
            line_item_uid: eIWl7X0nMuO9Ewbh0ChIx
            order_id: jJNGHm4gLI6XkFbwtiSLqK72KkAZY
          gift_card_id: gftc:6d55a72470d940c6ba09c0ab8ad08d20
          location_id: 81FN9BNFZTKS4
          type: ACTIVATE
        idempotency_key: U16kfr-kA70er-q4Rsym-7U7NnY
    CreateGiftCardActivityResponse:
      type: object
      description: >-
        A response that contains a `GiftCardActivity` that was created.

        The response might contain a set of `Error` objects if the request
        resulted in errors.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        gift_card_activity:
          $ref: '#/components/schemas/GiftCardActivity'
          description: The gift card activity that was created.
      example:
        gift_card_activity:
          activate_activity_details:
            amount_money:
              amount: 1000
              currency: USD
            line_item_uid: eIWl7X0nMuO9Ewbh0ChIx
            order_id: jJNGHm4gLI6XkFbwtiSLqK72KkAZY
          created_at: '2021-05-20T22:26:54.000Z'
          gift_card_balance_money:
            amount: 1000
            currency: USD
          gift_card_gan: '7783320002929081'
          gift_card_id: gftc:6d55a72470d940c6ba09c0ab8ad08d20
          id: gcact_c8f8cbf1f24b448d8ecf39ed03f97864
          location_id: 81FN9BNFZTKS4
          type: ACTIVATE
    CreateGiftCardRequest:
      type: object
      description: >-
        Represents a [CreateGiftCard](api-endpoint:GiftCards-CreateGiftCard)
        request.
      x-release-status: PUBLIC
      required:
        - idempotency_key
        - location_id
        - gift_card
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency.
            For more information, 

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          minLength: 1
          maxLength: 128
        location_id:
          type: string
          description: >-
            The ID of the [location](entity:Location) where the gift card should
            be registered for 

            reporting purposes. Gift cards can be redeemed at any of the
            seller's locations.
          minLength: 1
        gift_card:
          $ref: '#/components/schemas/GiftCard'
          description: >-
            The gift card to create. The `type` field is required for this
            request. The `gan_source` 

            and `gan` fields are included as follows: 


            To direct Square to generate a 16-digit GAN, omit `gan_source` and
            `gan`.


            To provide a custom GAN, include `gan_source` and `gan`.

            - For `gan_source`, specify `OTHER`. 

            - For `gan`, provide a custom GAN containing 8 to 20 alphanumeric
            characters. The GAN must be 

            unique for the seller and cannot start with the same bank
            identification number (BIN) as major 

            credit cards. Do not use GANs that are easy to guess (such as
            12345678) because they greatly 

            increase the risk of fraud. It is the responsibility of the
            developer to ensure the security 

            of their custom GANs. For more information, see 

            [Custom
            GANs](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api#custom-gans). 


            To register an unused, physical gift card that the seller previously
            ordered from Square, 

            include `gan` and provide the GAN that is printed on the gift card.
      example:
        gift_card:
          type: DIGITAL
        idempotency_key: NC9Tm69EjbjtConu
        location_id: 81FN9BNFZTKS4
    CreateGiftCardResponse:
      type: object
      description: >-
        A response that contains a `GiftCard`. The response might contain a set
        of `Error` objects if the request

        resulted in errors.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        gift_card:
          $ref: '#/components/schemas/GiftCard'
          description: The new gift card.
      example:
        gift_card:
          balance_money:
            amount: 0
            currency: USD
          created_at: '2021-05-20T22:26:54.000Z'
          gan: '7783320006753271'
          gan_source: SQUARE
          id: gftc:6cbacbb64cf54e2ca9f573d619038059
          state: PENDING
          type: DIGITAL
    CreateInvoiceAttachmentRequest:
      type: object
      description: >-
        Represents a
        [CreateInvoiceAttachment](api-endpoint:Invoices-CreateInvoiceAttachment)
        request.
      x-release-status: PUBLIC
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies the `CreateInvoiceAttachment`
            request.

            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 128
        description:
          type: string
          description: The description of the attachment to display on the invoice.
          maxLength: 128
      example:
        description: Service contract
        idempotency_key: ae5e84f9-4742-4fc1-ba12-a3ce3748f1c3
    CreateInvoiceAttachmentResponse:
      type: object
      description: >-
        Represents a
        [CreateInvoiceAttachment](api-endpoint:Invoices-CreateInvoiceAttachment)
        response.
      x-release-status: PUBLIC
      properties:
        attachment:
          $ref: '#/components/schemas/InvoiceAttachment'
          description: Metadata about the attachment that was added to the invoice.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example:
        attachment:
          description: Service contract
          filename: file.jpg
          filesize: 102705
          hash: 273ee02cb6f5f8a3a8ca23604930dd53
          id: inva:0-3bB9ZuDHiziThQhuC4fwWt
          mime_type: image/jpeg
          uploaded_at: '2023-02-03T20:28:14Z'
    CreateInvoiceRequest:
      type: object
      description: Describes a `CreateInvoice` request.
      x-release-status: PUBLIC
      required:
        - invoice
      properties:
        invoice:
          $ref: '#/components/schemas/Invoice'
          description: The invoice to create.
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies the `CreateInvoice` request. If you
            do not 

            provide `idempotency_key` (or provide an empty string as the value),
            the endpoint 

            treats each request as independent.


            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 128
      example:
        idempotency_key: ce3748f9-5fc1-4762-aa12-aae5e843f1f4
        invoice:
          accepted_payment_methods:
            bank_account: false
            buy_now_pay_later: false
            card: true
            cash_app_pay: false
            square_gift_card: false
          custom_fields:
            - label: Event Reference Number
              placement: ABOVE_LINE_ITEMS
              value: 'Ref. #1234'
            - label: Terms of Service
              placement: BELOW_LINE_ITEMS
              value: The terms of service are...
          delivery_method: EMAIL
          description: We appreciate your business!
          invoice_number: inv-100
          location_id: ES0RJRZYEC39A
          order_id: CAISENgvlJ6jLWAzERDzjyHVybY
          payment_requests:
            - automatic_payment_source: NONE
              due_date: '2030-01-24'
              reminders:
                - message: Your invoice is due tomorrow
                  relative_scheduled_days: -1
              request_type: BALANCE
              tipping_enabled: true
          primary_recipient:
            customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4
          sale_or_service_date: '2030-01-24'
          scheduled_at: '2030-01-13T10:00:00Z'
          store_payment_method_enabled: false
          title: Event Planning Services
    CreateInvoiceResponse:
      type: object
      description: The response returned by the `CreateInvoice` request.
      x-release-status: PUBLIC
      properties:
        invoice:
          $ref: '#/components/schemas/Invoice'
          description: The newly created invoice.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example:
        invoice:
          accepted_payment_methods:
            bank_account: false
            buy_now_pay_later: false
            card: true
            cash_app_pay: false
            square_gift_card: false
          created_at: '2020-06-18T17:45:13Z'
          custom_fields:
            - label: Event Reference Number
              placement: ABOVE_LINE_ITEMS
              value: 'Ref. #1234'
            - label: Terms of Service
              placement: BELOW_LINE_ITEMS
              value: The terms of service are...
          delivery_method: EMAIL
          description: We appreciate your business!
          id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
          invoice_number: inv-100
          location_id: ES0RJRZYEC39A
          order_id: CAISENgvlJ6jLWAzERDzjyHVybY
          payment_requests:
            - automatic_payment_source: NONE
              computed_amount_money:
                amount: 10000
                currency: USD
              due_date: '2030-01-24'
              reminders:
                - message: Your invoice is due tomorrow
                  relative_scheduled_days: -1
                  status: PENDING
                  uid: beebd363-e47f-4075-8785-c235aaa7df11
              request_type: BALANCE
              tipping_enabled: true
              total_completed_amount_money:
                amount: 0
                currency: USD
              uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355
          primary_recipient:
            customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4
            email_address: Amelia.Earhart@example.com
            family_name: Earhart
            given_name: Amelia
            phone_number: 1-212-555-4240
          sale_or_service_date: '2030-01-24'
          scheduled_at: '2030-01-13T10:00:00Z'
          status: DRAFT
          store_payment_method_enabled: false
          timezone: America/Los_Angeles
          title: Event Planning Services
          updated_at: '2020-06-18T17:45:13Z'
          version: 0
    CreateJobRequest:
      type: object
      description: Represents a [CreateJob](api-endpoint:Team-CreateJob) request.
      x-release-status: BETA
      required:
        - job
        - idempotency_key
      properties:
        job:
          $ref: '#/components/schemas/Job'
          description: >-
            The job to create. The `title` field is required and
            `is_tip_eligible` defaults to true.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for the `CreateJob` request. Keys can be any
            valid string,

            but must be unique for each request. For more information, see

            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          minLength: 1
          maxLength: 45
      example:
        idempotency_key: idempotency-key-0
        job:
          is_tip_eligible: true
          title: Cashier
    CreateJobResponse:
      type: object
      description: >-
        Represents a [CreateJob](api-endpoint:Team-CreateJob) response. Either
        `job` or `errors`

        is present in the response.
      x-release-status: BETA
      properties:
        job:
          $ref: '#/components/schemas/Job'
          description: The new job.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: The errors that occurred during the request.
      example:
        job:
          created_at: '2021-06-11T22:55:45Z'
          id: 1yJlHapkseYnNPETIU1B
          is_tip_eligible: true
          title: Cashier
          updated_at: '2021-06-11T22:55:45Z'
          version: 1
    CreateLocationCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents a
        [CreateLocationCustomAttributeDefinition](api-endpoint:LocationCustomAttributes-CreateLocationCustomAttributeDefinition)
        request.
      x-release-status: BETA
      required:
        - custom_attribute_definition
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The custom attribute definition to create. Note the following:

            - With the exception of the `Selection` data type, the `schema` is
            specified as a simple URL to the JSON schema

            definition hosted on the Square CDN. For more information, including
            supported values and constraints, see

            [Supported data
            types](https://developer.squareup.com/docs/devtools/customattributes/overview#supported-data-types).

            - `name` is required unless `visibility` is set to
            `VISIBILITY_HIDDEN`.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency.
            For more information,

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
      example:
        custom_attribute_definition:
          description: Bestselling item at location
          key: bestseller
          name: Bestseller
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          visibility: VISIBILITY_READ_WRITE_VALUES
    CreateLocationCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a
        [CreateLocationCustomAttributeDefinition](api-endpoint:LocationCustomAttributes-CreateLocationCustomAttributeDefinition)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: BETA
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The new custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2022-12-02T19:06:36.559Z'
          description: Bestselling item at location
          key: bestseller
          name: Bestseller
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          updated_at: '2022-12-02T19:06:36.559Z'
          version: 1
          visibility: VISIBILITY_READ_WRITE_VALUES
    CreateLocationRequest:
      type: object
      description: >-
        The request object for the
        [CreateLocation](api-endpoint:Locations-CreateLocation) endpoint.
      x-release-status: PUBLIC
      properties:
        location:
          $ref: '#/components/schemas/Location'
          description: >-
            The initial values of the location being created. The `name` field
            is required and must be unique within a seller account.

            All other fields are optional, but any information you care about
            for the location should be included.

            The remaining fields are automatically added based on the data from
            the [main
            location](https://developer.squareup.com/docs/locations-api#about-the-main-location).
      example:
        location:
          address:
            address_line_1: 1234 Peachtree St. NE
            administrative_district_level_1: GA
            locality: Atlanta
            postal_code: '30309'
          description: Midtown Atlanta store
          name: Midtown
    CreateLocationResponse:
      type: object
      description: >-
        The response object returned by the
        [CreateLocation](api-endpoint:Locations-CreateLocation) endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: >-
            Information about
            [errors](https://developer.squareup.com/docs/build-basics/handling-errors)
            encountered during the request.
        location:
          $ref: '#/components/schemas/Location'
          description: The newly created `Location` object.
      example:
        location:
          address:
            address_line_1: 1234 Peachtree St. NE
            administrative_district_level_1: GA
            locality: Atlanta
            postal_code: '30309'
          business_name: Jet Fuel Coffee
          capabilities:
            - CREDIT_CARD_PROCESSING
          coordinates:
            latitude: 33.7889
            longitude: -84.3841
          country: US
          created_at: '2022-02-19T17:58:25Z'
          currency: USD
          description: Midtown Atlanta store
          id: 3Z4V4WHQK64X9
          language_code: en-US
          mcc: '7299'
          merchant_id: 3MYCJG5GVYQ8Q
          name: Midtown
          status: ACTIVE
          timezone: America/New_York
          type: PHYSICAL
    CreateLoyaltyAccountRequest:
      type: object
      description: A request to create a new loyalty account.
      x-release-status: PUBLIC
      required:
        - loyalty_account
        - idempotency_key
      properties:
        loyalty_account:
          $ref: '#/components/schemas/LoyaltyAccount'
          description: The loyalty account to create.
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this `CreateLoyaltyAccount`
            request. 

            Keys can be any valid string, but must be unique for every request.
          minLength: 1
          maxLength: 128
      example:
        idempotency_key: ec78c477-b1c3-4899-a209-a4e71337c996
        loyalty_account:
          mapping:
            phone_number: '+14155551234'
          program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
    CreateLoyaltyAccountResponse:
      type: object
      description: A response that includes loyalty account created.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        loyalty_account:
          $ref: '#/components/schemas/LoyaltyAccount'
          description: The newly created loyalty account.
      example:
        loyalty_account:
          balance: 0
          created_at: '2020-05-08T21:44:32Z'
          customer_id: QPTXM8PQNX3Q726ZYHPMNP46XC
          id: 79b807d2-d786-46a9-933b-918028d7a8c5
          lifetime_points: 0
          mapping:
            created_at: '2020-05-08T21:44:32Z'
            id: 66aaab3f-da99-49ed-8b19-b87f851c844f
            phone_number: '+14155551234'
          program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
          updated_at: '2020-05-08T21:44:32Z'
    CreateLoyaltyPromotionRequest:
      type: object
      description: >-
        Represents a
        [CreateLoyaltyPromotion](api-endpoint:Loyalty-CreateLoyaltyPromotion)
        request.
      x-release-status: PUBLIC
      x-params-example: '?program_id=d619f755-2d17-41f3-990d-c04ecedd64dd'
      required:
        - loyalty_promotion
        - idempotency_key
      properties:
        loyalty_promotion:
          $ref: '#/components/schemas/LoyaltyPromotion'
          description: The loyalty promotion to create.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, which is used to ensure
            idempotency. For more information,

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          minLength: 1
          maxLength: 128
      example:
        idempotency_key: ec78c477-b1c3-4899-a209-a4e71337c996
        loyalty_promotion:
          available_time:
            time_periods:
              - |-
                BEGIN:VEVENT
                DTSTART:20220816T160000
                DURATION:PT2H
                RRULE:FREQ=WEEKLY;BYDAY=TU
                END:VEVENT
          incentive:
            points_multiplier_data:
              multiplier: '3.0'
            type: POINTS_MULTIPLIER
          minimum_spend_amount_money:
            amount: 2000
            currency: USD
          name: Tuesday Happy Hour Promo
          qualifying_category_ids:
            - XTQPYLR3IIU9C44VRCB3XD12
          trigger_limit:
            interval: DAY
            times: 1
    CreateLoyaltyPromotionResponse:
      type: object
      description: >-
        Represents a
        [CreateLoyaltyPromotion](api-endpoint:Loyalty-CreateLoyaltyPromotion)
        response.

        Either `loyalty_promotion` or `errors` is present in the response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        loyalty_promotion:
          $ref: '#/components/schemas/LoyaltyPromotion'
          description: The new loyalty promotion.
      example:
        loyalty_promotion:
          available_time:
            start_date: '2022-08-16'
            time_periods:
              - |-
                BEGIN:VEVENT
                DTSTART:20220816T160000
                DURATION:PT2H
                RRULE:FREQ=WEEKLY;BYDAY=TU
                END:VEVENT
          created_at: '2022-08-16T08:38:54Z'
          id: loypromo_f0f9b849-725e-378d-b810-511237e07b67
          incentive:
            points_multiplier_data:
              multiplier: '3.000'
              points_multiplier: 3
            type: POINTS_MULTIPLIER
          loyalty_program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
          minimum_spend_amount_money:
            amount: 2000
            currency: USD
          name: Tuesday Happy Hour Promo
          qualifying_category_ids:
            - XTQPYLR3IIU9C44VRCB3XD12
          status: ACTIVE
          trigger_limit:
            interval: DAY
            times: 1
          updated_at: '2022-08-16T08:38:54Z'
    CreateLoyaltyRewardRequest:
      type: object
      description: A request to create a loyalty reward.
      x-release-status: PUBLIC
      required:
        - reward
        - idempotency_key
      properties:
        reward:
          $ref: '#/components/schemas/LoyaltyReward'
          description: The reward to create.
        idempotency_key:
          type: string
          description: |-
            A unique string that identifies this `CreateLoyaltyReward` request. 
            Keys can be any valid string, but must be unique for every request.
          minLength: 1
          maxLength: 128
      example:
        idempotency_key: 18c2e5ea-a620-4b1f-ad60-7b167285e451
        reward:
          loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
          order_id: RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY
          reward_tier_id: e1b39225-9da5-43d1-a5db-782cdd8ad94f
    CreateLoyaltyRewardResponse:
      type: object
      description: A response that includes the loyalty reward created.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        reward:
          $ref: '#/components/schemas/LoyaltyReward'
          description: The loyalty reward created.
      example:
        reward:
          created_at: '2020-05-01T21:49:54Z'
          id: a8f43ebe-2ad6-3001-bdd5-7d7c2da08943
          loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
          order_id: RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY
          points: 10
          reward_tier_id: e1b39225-9da5-43d1-a5db-782cdd8ad94f
          status: ISSUED
          updated_at: '2020-05-01T21:49:54Z'
    CreateMerchantCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents a
        [CreateMerchantCustomAttributeDefinition](api-endpoint:MerchantCustomAttributes-CreateMerchantCustomAttributeDefinition)
        request.
      x-release-status: BETA
      required:
        - custom_attribute_definition
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The custom attribute definition to create. Note the following:

            - With the exception of the `Selection` data type, the `schema` is
            specified as a simple URL to the JSON schema

            definition hosted on the Square CDN. For more information, including
            supported values and constraints, see

            [Supported data
            types](https://developer.squareup.com/docs/devtools/customattributes/overview#supported-data-types).

            - `name` is required unless `visibility` is set to
            `VISIBILITY_HIDDEN`.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency.
            For more information,

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
      example:
        custom_attribute_definition:
          description: This is the other name this merchant goes by.
          key: alternative_seller_name
          name: Alternative Merchant Name
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          visibility: VISIBILITY_READ_ONLY
    CreateMerchantCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a
        [CreateMerchantCustomAttributeDefinition](api-endpoint:MerchantCustomAttributes-CreateMerchantCustomAttributeDefinition)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: BETA
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The new custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2023-05-05T19:06:36.559Z'
          description: This is the other name this merchant goes by.
          key: alternative_seller_name
          name: Alternative Merchant Name
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          updated_at: '2023-05-05T19:06:36.559Z'
          version: 1
          visibility: VISIBILITY_READ_ONLY
    CreateMobileAuthorizationCodeRequest:
      type: object
      description: |-
        Defines the body parameters that can be provided in a request to the
        `CreateMobileAuthorizationCode` endpoint.
      x-release-status: PUBLIC
      properties:
        location_id:
          type: string
          description: >-
            The Square location ID that the authorization code should be tied
            to.
          minLength: 1
          maxLength: 191
      example:
        location_id: YOUR_LOCATION_ID
    CreateMobileAuthorizationCodeResponse:
      type: object
      description: |-
        Defines the fields that are included in the response body of
        a request to the `CreateMobileAuthorizationCode` endpoint.
      x-release-status: PUBLIC
      properties:
        authorization_code:
          type: string
          description: >-
            The generated authorization code that connects a mobile application
            instance

            to a Square account.
          maxLength: 191
        expires_at:
          type: string
          description: >-
            The timestamp when `authorization_code` expires, in

            [RFC 3339](https://tools.ietf.org/html/rfc3339) format (for example,
            "2016-09-04T23:59:33.123Z").
          minLength: 20
          maxLength: 48
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        authorization_code: YOUR_MOBILE_AUTHORIZATION_CODE
        expires_at: '2019-01-10T19:42:08Z'
    CreateOrderCustomAttributeDefinitionRequest:
      type: object
      description: Represents a create request for an order custom attribute definition.
      x-release-status: BETA
      required:
        - custom_attribute_definition
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The custom attribute definition to create. Note the following:

            - With the exception of the `Selection` data type, the `schema` is
            specified as a simple URL to the JSON schema

            definition hosted on the Square CDN. For more information, including
            supported values and constraints, see

            [Specifying the
            schema](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attribute-definitions#specify-schema).

            - If provided, `name` must be unique (case-sensitive) across all
            visible customer-related custom attribute definitions for the
            seller.

            - All custom attributes are visible in exported customer data,
            including those set to `VISIBILITY_HIDDEN`.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency. 

            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          minLength: 1
          maxLength: 45
      example:
        custom_attribute_definition:
          description: The number of people seated at a table
          key: cover-count
          name: Cover count
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number
          visibility: VISIBILITY_READ_WRITE_VALUES
        idempotency_key: IDEMPOTENCY_KEY
    CreateOrderCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a response from creating an order custom attribute
        definition.
      x-release-status: BETA
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The new custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2022-10-06T16:53:23.141Z'
          description: The number of people seated at a table
          key: cover-count
          name: Cover count
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number
          updated_at: '2022-10-06T16:53:23.141Z'
          version: 1
          visibility: VISIBILITY_READ_WRITE_VALUES
    CreateOrderRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        order:
          $ref: '#/components/schemas/Order'
          description: >-
            The order to create. If this field is set, the only other top-level
            field that can be

            set is the `idempotency_key`.
        idempotency_key:
          type: string
          description: >-
            A value you specify that uniquely identifies this

            order among orders you have created.


            If you are unsure whether a particular order was created
            successfully,

            you can try it again with the same idempotency key without

            worrying about creating duplicate orders.


            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 192
      example:
        idempotency_key: 8193148c-9586-11e6-99f9-28cfe92138cf
        order:
          discounts:
            - name: Labor Day Sale
              percentage: '5'
              scope: ORDER
              uid: labor-day-sale
            - catalog_object_id: DB7L55ZH2BGWI4H23ULIWOQ7
              scope: ORDER
              uid: membership-discount
            - amount_money:
                amount: 100
                currency: USD
              name: Sale - $1.00 off
              scope: LINE_ITEM
              uid: one-dollar-off
          line_items:
            - base_price_money:
                amount: 1599
                currency: USD
              name: New York Strip Steak
              quantity: '1'
            - applied_discounts:
                - discount_uid: one-dollar-off
              catalog_object_id: BEMYCSMIJL46OCDV4KYIKXIB
              modifiers:
                - catalog_object_id: CHQX7Y4KY6N5KINJKZCFURPZ
              quantity: '2'
          location_id: 057P5VYJ4A5X1
          reference_id: my-order-001
          taxes:
            - name: State Sales Tax
              percentage: '9'
              scope: ORDER
              uid: state-sales-tax
    CreateOrderResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the `CreateOrder` endpoint.


        Either `errors` or `order` is present in a given response, but never
        both.
      x-release-status: PUBLIC
      properties:
        order:
          $ref: '#/components/schemas/Order'
          description: The newly created order.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        order:
          created_at: '2020-01-17T20:47:53.293Z'
          discounts:
            - applied_money:
                amount: 30
                currency: USD
              catalog_object_id: DB7L55ZH2BGWI4H23ULIWOQ7
              name: Membership Discount
              percentage: '0.5'
              scope: ORDER
              type: FIXED_PERCENTAGE
              uid: membership-discount
            - applied_money:
                amount: 303
                currency: USD
              name: Labor Day Sale
              percentage: '5'
              scope: ORDER
              type: FIXED_PERCENTAGE
              uid: labor-day-sale
            - amount_money:
                amount: 100
                currency: USD
              applied_money:
                amount: 100
                currency: USD
              name: Sale - $1.00 off
              scope: LINE_ITEM
              type: FIXED_AMOUNT
              uid: one-dollar-off
          id: CAISENgvlJ6jLWAzERDzjyHVybY
          line_items:
            - applied_discounts:
                - applied_money:
                    amount: 8
                    currency: USD
                  discount_uid: membership-discount
                  uid: jWdgP1TpHPFBuVrz81mXVC
                - applied_money:
                    amount: 79
                    currency: USD
                  discount_uid: labor-day-sale
                  uid: jnZOjjVY57eRcQAVgEwFuC
              applied_taxes:
                - applied_money:
                    amount: 136
                    currency: USD
                  tax_uid: state-sales-tax
                  uid: aKG87ArnDpvMLSZJHxWUl
              base_price_money:
                amount: 1599
                currency: USD
              gross_sales_money:
                amount: 1599
                currency: USD
              name: New York Strip Steak
              quantity: '1'
              total_discount_money:
                amount: 87
                currency: USD
              total_money:
                amount: 1648
                currency: USD
              total_service_charge_money:
                amount: 0
                currency: USD
              total_tax_money:
                amount: 136
                currency: USD
              uid: 8uSwfzvUImn3IRrvciqlXC
              variation_total_price_money:
                amount: 1599
                currency: USD
            - applied_discounts:
                - applied_money:
                    amount: 22
                    currency: USD
                  discount_uid: membership-discount
                  uid: nUXvdsIItfKko0dbYtY58C
                - applied_money:
                    amount: 224
                    currency: USD
                  discount_uid: labor-day-sale
                  uid: qSdkOOOernlVQqsJ94SPjB
                - applied_money:
                    amount: 100
                    currency: USD
                  discount_uid: one-dollar-off
                  uid: y7bVl4njrWAnfDwmz19izB
              applied_taxes:
                - applied_money:
                    amount: 374
                    currency: USD
                  tax_uid: state-sales-tax
                  uid: v1dAgrfUVUPTnVTf9sRPz
              base_price_money:
                amount: 2200
                currency: USD
              catalog_object_id: BEMYCSMIJL46OCDV4KYIKXIB
              gross_sales_money:
                amount: 4500
                currency: USD
              modifiers:
                - base_price_money:
                    amount: 50
                    currency: USD
                  catalog_object_id: CHQX7Y4KY6N5KINJKZCFURPZ
                  name: Well
                  total_price_money:
                    amount: 100
                    currency: USD
                  uid: Lo3qMMckDluu9Qsb58d4CC
              name: New York Steak
              quantity: '2'
              total_discount_money:
                amount: 346
                currency: USD
              total_money:
                amount: 4528
                currency: USD
              total_service_charge_money:
                amount: 0
                currency: USD
              total_tax_money:
                amount: 374
                currency: USD
              uid: v8ZuEXpOJpb0bazLuvrLDB
              variation_name: Larger
              variation_total_price_money:
                amount: 4400
                currency: USD
          location_id: 057P5VYJ4A5X1
          net_amounts:
            discount_money:
              amount: 433
              currency: USD
            service_charge_money:
              amount: 0
              currency: USD
            tax_money:
              amount: 510
              currency: USD
            tip_money:
              amount: 0
              currency: USD
            total_money:
              amount: 6176
              currency: USD
          reference_id: my-order-001
          source:
            name: My App
          state: OPEN
          taxes:
            - applied_money:
                amount: 510
                currency: USD
              name: State Sales Tax
              percentage: '9'
              scope: ORDER
              type: ADDITIVE
              uid: state-sales-tax
          total_discount_money:
            amount: 433
            currency: USD
          total_money:
            amount: 6176
            currency: USD
          total_service_charge_money:
            amount: 0
            currency: USD
          total_tax_money:
            amount: 510
            currency: USD
          total_tip_money:
            amount: 0
            currency: USD
          updated_at: '2020-01-17T20:47:53.293Z'
          version: 1
    CreatePaymentLinkRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this `CreatePaymentLinkRequest`
            request.

            If you do not provide a unique string (or provide an empty string as
            the value),

            the endpoint treats each request as independent.


            For more information, see
            [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).
          maxLength: 192
        description:
          type: string
          description: >-
            A description of the payment link. You provide this optional
            description that is useful in your

            application context. It is not used anywhere.
          maxLength: 4096
        quick_pay:
          $ref: '#/components/schemas/QuickPay'
          description: >-
            Describes an ad hoc item and price for which to generate a quick pay
            checkout link.

            For more information,

            see [Quick Pay
            Checkout](https://developer.squareup.com/docs/checkout-api/quick-pay-checkout).
        order:
          $ref: '#/components/schemas/Order'
          description: >-
            Describes the `Order` for which to create a checkout link.

            For more information,

            see [Square Order
            Checkout](https://developer.squareup.com/docs/checkout-api/square-order-checkout).
        checkout_options:
          $ref: '#/components/schemas/CheckoutOptions'
          description: >-
            Describes optional fields to add to the resulting checkout page.

            For more information,

            see [Optional Checkout
            Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations).
        pre_populated_data:
          $ref: '#/components/schemas/PrePopulatedData'
          description: >-
            Describes fields to prepopulate in the resulting checkout page.

            For more information, see [Prepopulate the shipping
            address](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations#prepopulate-the-shipping-address).
        payment_note:
          type: string
          description: >-
            A note for the payment. After processing the payment, Square adds
            this note to the resulting `Payment`.
          maxLength: 500
      example:
        idempotency_key: cd9e25dc-d9f2-4430-aedb-61605070e95f
        quick_pay:
          location_id: A9Y43N9ABXZBP
          name: Auto Detailing
          price_money:
            amount: 10000
            currency: USD
    CreatePaymentLinkResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        payment_link:
          $ref: '#/components/schemas/PaymentLink'
          description: The created payment link.
        related_resources:
          $ref: '#/components/schemas/PaymentLinkRelatedResources'
          description: The list of related objects.
      example:
        payment_link:
          created_at: '2022-04-25T23:58:01Z'
          id: PKVT6XGJZXYUP3NZ
          long_url: https://checkout.square.site/EXAMPLE
          order_id: o4b7saqp4HzhNttf5AJxC0Srjd4F
          url: https://square.link/u/EXAMPLE
          version: 1
        related_resources:
          orders:
            - created_at: '2022-03-03T00:53:15.829Z'
              fulfillments:
                - state: PROPOSED
                  type: DIGITAL
                  uid: bBpNrxjdQxGQP16sTmdzi
              id: o4b7saqp4HzhNttf5AJxC0Srjd4F
              line_items:
                - base_price_money:
                    amount: 12500
                    currency: USD
                  gross_sales_money:
                    amount: 12500
                    currency: USD
                  item_type: ITEM
                  name: Auto Detailing
                  quantity: '1'
                  total_discount_money:
                    amount: 0
                    currency: USD
                  total_money:
                    amount: 12500
                    currency: USD
                  total_tax_money:
                    amount: 0
                    currency: USD
                  uid: 8YX13D1U3jO7czP8JVrAR
                  variation_total_price_money:
                    amount: 12500
                    currency: USD
              location_id: '{LOCATION_ID}'
              net_amounts:
                discount_money:
                  amount: 0
                  currency: USD
                service_charge_money:
                  amount: 0
                  currency: USD
                tax_money:
                  amount: 0
                  currency: USD
                tip_money:
                  amount: 0
                  currency: USD
                total_money:
                  amount: 12500
                  currency: USD
              source:
                name: Test Online Checkout Application
              state: DRAFT
              total_discount_money:
                amount: 0
                currency: USD
              total_money:
                amount: 12500
                currency: USD
              total_service_charge_money:
                amount: 0
                currency: USD
              total_tax_money:
                amount: 0
                currency: USD
              total_tip_money:
                amount: 0
                currency: USD
              updated_at: '2022-03-03T00:53:15.829Z'
              version: 1
    CreatePaymentRequest:
      type: object
      description: |-
        Describes a request to create a payment using 
        [CreatePayment](api-endpoint:Payments-CreatePayment).
      x-release-status: PUBLIC
      required:
        - source_id
        - idempotency_key
      properties:
        source_id:
          type: string
          description: >-
            The ID for the source of funds for this payment.

            This could be a payment token generated by the Web Payments SDK for
            any of its

            [supported
            methods](https://developer.squareup.com/docs/web-payments/overview#explore-payment-methods),

            including cards, bank transfers, Afterpay or Cash App Pay. If
            recording a payment

            that the seller received outside of Square, specify either "CASH" or
            "EXTERNAL".

            For more information, see 

            [Take
            Payments](https://developer.squareup.com/docs/payments-api/take-payments).
          minLength: 1
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this `CreatePayment` request. Keys
            can be any valid string

            but must be unique for every `CreatePayment` request.


            Note: The number of allowed characters might be less than the stated
            maximum, if multi-byte

            characters are used.


            For more information, see
            [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).
          minLength: 1
          maxLength: 45
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money to accept for this payment, not including
            `tip_money`.


            The amount must be specified in the smallest denomination of the
            applicable currency

            (for example, US dollar amounts are specified in cents). For more
            information, see

            [Working with Monetary
            Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).


            The currency code must match the currency associated with the
            business

            that is accepting the payment.
        tip_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount designated as a tip, in addition to `amount_money`.


            The amount must be specified in the smallest denomination of the
            applicable currency

            (for example, US dollar amounts are specified in cents). For more
            information, see

            [Working with Monetary
            Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).


            The currency code must match the currency associated with the
            business

            that is accepting the payment.
        app_fee_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money that the developer is taking as a fee

            for facilitating the payment on behalf of the seller.


            The amount cannot be more than 90% of the total amount of the
            payment.


            The amount must be specified in the smallest denomination of the
            applicable currency

            (for example, US dollar amounts are specified in cents). For more
            information, see

            [Working with Monetary
            Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).


            The fee currency code must match the currency associated with the
            seller

            that is accepting the payment. The application must be from a
            developer

            account in the same country and using the same currency code as the
            seller.


            For more information about the application fee scenario, see

            [Take Payments and Collect
            Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).


            To set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth
            permission is required.

            For more information, see
            [Permissions](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees#permissions).
        delay_duration:
          type: string
          description: >-
            The duration of time after the payment's creation when Square
            automatically 

            either completes or cancels the payment depending on the
            `delay_action` field value. 

            For more information, see 

            [Time
            threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). 


            This parameter should be specified as a time duration, in RFC 3339
            format.


            Note: This feature is only supported for card payments. This
            parameter can only be set for a delayed

            capture payment (`autocomplete=false`).


            Default:


            - Card-present payments: "PT36H" (36 hours) from the creation time.

            - Card-not-present payments: "P7D" (7 days) from the creation time.
        delay_action:
          type: string
          description: >-
            The action to be applied to the payment when the `delay_duration`
            has elapsed. The action must be

            CANCEL or COMPLETE. For more information, see 

            [Time
            Threshold](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold). 


            Default: CANCEL
        autocomplete:
          type: boolean
          description: >-
            If set to `true`, this payment will be completed when possible. If

            set to `false`, this payment is held in an approved state until
            either

            explicitly completed (captured) or canceled (voided). For more
            information, see

            [Delayed
            capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments#delayed-capture-of-a-card-payment).


            Default: true
        order_id:
          type: string
          description: Associates a previously created order with this payment.
        customer_id:
          type: string
          description: >-
            The [Customer](entity:Customer) ID of the customer associated with
            the payment.


            This is required if the `source_id` refers to a card on file created
            using the Cards API.
        location_id:
          type: string
          description: >-
            The location ID to associate with the payment. If not specified, the
            [main
            location](https://developer.squareup.com/docs/locations-api#about-the-main-location)
            is

            used.
        team_member_id:
          type: string
          description: |-
            An optional [TeamMember](entity:TeamMember) ID to associate with 
            this payment.
        reference_id:
          type: string
          description: >-
            A user-defined ID to associate with the payment.


            You can use this field to associate the payment to an entity in an
            external system 

            (for example, you might specify an order ID that is generated by a
            third-party shopping cart).
          maxLength: 40
        verification_token:
          type: string
          description: >-
            An identifying token generated by
            [payments.verifyBuyer()](https://developer.squareup.com/reference/sdks/web/payments/objects/Payments#Payments.verifyBuyer).

            Verification tokens encapsulate customer device information and 3-D
            Secure

            challenge results to indicate that Square has verified the buyer
            identity.


            For more information, see [SCA
            Overview](https://developer.squareup.com/docs/sca-overview).
        accept_partial_authorization:
          type: boolean
          description: >-
            If set to `true` and charging a Square Gift Card, a payment might be
            returned with

            `amount_money` equal to less than what was requested. For example, a
            request for $20 when charging

            a Square Gift Card with a balance of $5 results in an APPROVED
            payment of $5. You might choose

            to prompt the buyer for an additional payment to cover the remainder
            or cancel the Gift Card

            payment. This field cannot be `true` when `autocomplete = true`.


            For more information, see

            [Partial amount with Square Gift
            Cards](https://developer.squareup.com/docs/payments-api/take-payments#partial-payment-gift-card).


            Default: false
        buyer_email_address:
          type: string
          description: The buyer's email address.
          maxLength: 255
        buyer_phone_number:
          type: string
          description: >-
            The buyer's phone number.

            Must follow the following format:

            1. A leading + symbol (followed by a country code)

            2. The phone number can contain spaces and the special characters
            `(` , `)` , `-` , and `.`.

            Alphabetical characters aren't allowed.

            3. The phone number must contain between 9 and 16 digits.
        billing_address:
          $ref: '#/components/schemas/Address'
          description: The buyer's billing address.
        shipping_address:
          $ref: '#/components/schemas/Address'
          description: The buyer's shipping address.
        note:
          type: string
          description: >-
            An optional note to be entered by the developer when creating a
            payment.
          maxLength: 500
        statement_description_identifier:
          type: string
          description: >-
            Optional additional payment information to include on the customer's
            card statement

            as part of the statement description. This can be, for example, an
            invoice number, ticket number,

            or short description that uniquely identifies the purchase.


            Note that the `statement_description_identifier` might get truncated
            on the statement description

            to fit the required information including the Square identifier (SQ
            *) and name of the

            seller taking the payment.
          maxLength: 20
        cash_details:
          $ref: '#/components/schemas/CashPaymentDetails'
          description: >-
            Additional details required when recording a cash payment
            (`source_id` is CASH).
        external_details:
          $ref: '#/components/schemas/ExternalPaymentDetails'
          description: >-
            Additional details required when recording an external payment
            (`source_id` is EXTERNAL).
        customer_details:
          $ref: '#/components/schemas/CustomerDetails'
          description: Details about the customer making the payment.
        offline_payment_details:
          $ref: '#/components/schemas/OfflinePaymentDetails'
          description: >-
            An optional field for specifying the offline payment details. This
            is intended for

            internal 1st-party callers only.
      example:
        amount_money:
          amount: 1000
          currency: USD
        app_fee_money:
          amount: 10
          currency: USD
        autocomplete: true
        customer_id: W92WH6P11H4Z77CTET0RNTGFW8
        idempotency_key: 7b0f3ec5-086a-4871-8f13-3c81b3875218
        location_id: L88917AVBK2S5
        note: Brief description
        reference_id: '123456'
        source_id: ccof:GaJGNaZa8x4OgDJn4GB
    CreatePaymentResponse:
      type: object
      description: >-
        Defines the response returned by
        [CreatePayment](api-endpoint:Payments-CreatePayment).


        If there are errors processing the request, the `payment` field might
        not be

        present, or it might be present with a status of `FAILED`.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        payment:
          $ref: '#/components/schemas/Payment'
          description: The newly created payment.
      example:
        payment:
          amount_money:
            amount: 1000
            currency: USD
          app_fee_money:
            amount: 10
            currency: USD
          application_details:
            application_id: sq0ids-TcgftTEtKxJTRF1lCFJ9TA
            square_product: ECOMMERCE_API
          approved_money:
            amount: 1000
            currency: USD
          card_details:
            auth_result_code: vNEn2f
            avs_status: AVS_ACCEPTED
            card:
              bin: '411111'
              card_brand: VISA
              card_type: DEBIT
              exp_month: 11
              exp_year: 2022
              fingerprint: >-
                sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ
              last_4: '1111'
              prepaid_type: NOT_PREPAID
            card_payment_timeline:
              authorized_at: '2021-10-13T21:14:29.732Z'
              captured_at: '2021-10-13T21:14:30.504Z'
            cvv_status: CVV_ACCEPTED
            entry_method: ON_FILE
            statement_description: SQ *EXAMPLE TEST GOSQ.C
            status: CAPTURED
          created_at: '2021-10-13T21:14:29.577Z'
          customer_id: W92WH6P11H4Z77CTET0RNTGFW8
          delay_action: CANCEL
          delay_duration: PT168H
          delayed_until: '2021-10-20T21:14:29.577Z'
          id: R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY
          location_id: L88917AVBK2S5
          note: Brief Description
          order_id: pRsjRTgFWATl7so6DxdKBJa7ssbZY
          receipt_number: R2B3
          receipt_url: https://squareup.com/receipt/preview/EXAMPLE_RECEIPT_ID
          reference_id: '123456'
          risk_evaluation:
            created_at: '2021-10-13T21:14:30.423Z'
            risk_level: NORMAL
          source_type: CARD
          status: COMPLETED
          total_money:
            amount: 1000
            currency: USD
          updated_at: '2021-10-13T21:14:30.504Z'
          version_token: TPtNEOBOa6Qq6E3C3IjckSVOM6b3hMbfhjvTxHBQUsB6o
    CreateRefundRequest:
      type: object
      description: >-
        Defines the body parameters that can be included in

        a request to the [CreateRefund](api-endpoint:Transactions-CreateRefund)
        endpoint.


        Deprecated - recommend using
        [RefundPayment](api-endpoint:Refunds-RefundPayment)
      x-release-status: DEPRECATED
      required:
        - idempotency_key
        - tender_id
        - amount_money
      properties:
        idempotency_key:
          type: string
          description: >-
            A value you specify that uniquely identifies this

            refund among refunds you've created for the tender.


            If you're unsure whether a particular refund succeeded,

            you can reattempt it with the same idempotency key without

            worrying about duplicating the refund.


            See [Idempotency
            keys](https://developer.squareup.com/docs/working-with-apis/idempotency)
            for more information.
          minLength: 1
          maxLength: 192
        tender_id:
          type: string
          description: >-
            The ID of the tender to refund.


            A [`Transaction`](entity:Transaction) has one or more `tenders`
            (i.e., methods

            of payment) associated with it, and you refund each tender
            separately with

            the Connect API.
          minLength: 1
          maxLength: 192
        reason:
          type: string
          description: |-
            A description of the reason for the refund.

            Default value: `Refund via API`
          maxLength: 192
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money to refund.


            Note that you specify the amount in the

            __smallest denomination of the applicable currency__. For example,
            US dollar

            amounts are specified in cents. See

            [Working with monetary
            amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)
            for details.


            This amount cannot exceed the amount that was originally charged to
            the

            tender that corresponds to `tender_id`.
      example:
        amount_money:
          amount: 100
          currency: USD
        idempotency_key: 86ae1696-b1e3-4328-af6d-f1e04d947ad2
        reason: a reason
        tender_id: MtZRYYdDrYNQbOvV7nbuBvMF
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/CreateRefund/CreateRefundRequest.csharp
        java: /sdk_samples/CreateRefund/CreateRefundRequest.java
        javascript: /sdk_samples/CreateRefund/CreateRefundRequest.javascript
        php: /sdk_samples/CreateRefund/CreateRefundRequest.php
        python: /sdk_samples/CreateRefund/CreateRefundRequest.python
        ruby: /sdk_samples/CreateRefund/CreateRefundRequest.ruby
    CreateRefundResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [CreateRefund](api-endpoint:Transactions-CreateRefund)
        endpoint.


        One of `errors` or `refund` is present in a given response (never both).
      x-release-status: DEPRECATED
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        refund:
          $ref: '#/components/schemas/Refund'
          description: The created refund.
      example:
        refund:
          additional_recipients:
            - amount_money:
                amount: 10
                currency: USD
              description: Application fees
              location_id: 057P5VYJ4A5X1
              receivable_id: ISu5xwxJ5v0CMJTQq7RvqyMF
          amount_money:
            amount: 100
            currency: USD
          created_at: '2016-02-12T00:28:18Z'
          id: b27436d1-7f8e-5610-45c6-417ef71434b4-SW
          location_id: 18YC4JDH91E1H
          reason: some reason
          status: PENDING
          tender_id: MtZRYYdDrYNQbOvV7nbuBvMF
          transaction_id: KnL67ZIwXCPtzOrqj0HrkxMF
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/CreateRefund/CreateRefundResponse.csharp
        java: /sdk_samples/CreateRefund/CreateRefundResponse.java
        javascript: /sdk_samples/CreateRefund/CreateRefundResponse.javascript
        php: /sdk_samples/CreateRefund/CreateRefundResponse.php
        python: /sdk_samples/CreateRefund/CreateRefundResponse.python
        ruby: /sdk_samples/CreateRefund/CreateRefundResponse.ruby
    CreateShiftRequest:
      type: object
      description: Represents a request to create a `Shift`.
      x-release-status: PUBLIC
      required:
        - shift
      properties:
        idempotency_key:
          type: string
          description: A unique string value to ensure the idempotency of the operation.
          maxLength: 128
        shift:
          $ref: '#/components/schemas/Shift'
          description: The `Shift` to be created.
      example:
        idempotency_key: HIDSNG5KS478L
        shift:
          breaks:
            - break_type_id: REGS1EQR1TPZ5
              end_at: '2019-01-25T06:16:00-05:00'
              expected_duration: PT5M
              is_paid: true
              name: Tea Break
              start_at: '2019-01-25T06:11:00-05:00'
          declared_cash_tip_money:
            amount: 500
            currency: USD
          end_at: '2019-01-25T13:11:00-05:00'
          location_id: PAA1RJZZKXBFG
          start_at: '2019-01-25T03:11:00-05:00'
          team_member_id: ormj0jJJZ5OZIzxrZYJI
          wage:
            hourly_rate:
              amount: 1100
              currency: USD
            tip_eligible: true
            title: Barista
    CreateShiftResponse:
      type: object
      description: |-
        The response to a request to create a `Shift`. The response contains
        the created `Shift` object and might contain a set of `Error` objects if
        the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        shift:
          $ref: '#/components/schemas/Shift'
          description: The `Shift` that was created on the request.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        shift:
          breaks:
            - break_type_id: REGS1EQR1TPZ5
              end_at: '2019-01-25T06:16:00-05:00'
              expected_duration: PT5M
              id: X7GAQYVVRRG6P
              is_paid: true
              name: Tea Break
              start_at: '2019-01-25T06:11:00-05:00'
          created_at: '2019-02-28T00:39:02Z'
          declared_cash_tip_money:
            amount: 500
            currency: USD
          employee_id: ormj0jJJZ5OZIzxrZYJI
          end_at: '2019-01-25T13:11:00-05:00'
          id: K0YH4CV5462JB
          location_id: PAA1RJZZKXBFG
          start_at: '2019-01-25T03:11:00-05:00'
          status: CLOSED
          team_member_id: ormj0jJJZ5OZIzxrZYJI
          timezone: America/New_York
          updated_at: '2019-02-28T00:39:02Z'
          version: 1
          wage:
            hourly_rate:
              amount: 1100
              currency: USD
            job_id: FzbJAtt9qEWncK1BWgVCxQ6M
            tip_eligible: true
            title: Barista
    CreateSubscriptionRequest:
      type: object
      description: >-
        Defines input parameters in a request to the 

        [CreateSubscription](api-endpoint:Subscriptions-CreateSubscription)
        endpoint.
      x-release-status: PUBLIC
      required:
        - location_id
        - customer_id
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this `CreateSubscription` request.

            If you do not provide a unique string (or provide an empty string as
            the value),

            the endpoint treats each request as independent.


            For more information, see [Idempotency
            keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
        location_id:
          type: string
          description: The ID of the location the subscription is associated with.
          minLength: 1
        plan_variation_id:
          type: string
          description: >-
            The ID of the [subscription plan
            variation](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations#plan-variations)
            created using the Catalog API.
        customer_id:
          type: string
          description: >-
            The ID of the [customer](entity:Customer) subscribing to the
            subscription plan variation.
          minLength: 1
        start_date:
          type: string
          description: |-
            The `YYYY-MM-DD`-formatted date to start the subscription. 
            If it is unspecified, the subscription starts immediately.
        canceled_date:
          type: string
          description: >-
            The `YYYY-MM-DD`-formatted date when the newly created subscription
            is scheduled for cancellation. 


            This date overrides the cancellation date set in the plan variation
            configuration.

            If the cancellation date is earlier than the end date of a
            subscription cycle, the subscription stops

            at the canceled date and the subscriber is sent a prorated invoice
            at the beginning of the canceled cycle. 


            When the subscription plan of the newly created subscription has a
            fixed number of cycles and the `canceled_date`

            occurs before the subscription plan expires, the specified
            `canceled_date` sets the date when the subscription 

            stops through the end of the last cycle.
        tax_percentage:
          type: string
          description: >-
            The tax to add 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%.
          maxLength: 10
        price_override_money:
          $ref: '#/components/schemas/Money'
          description: >-
            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).
        card_id:
          type: string
          description: >-
            The ID of the [subscriber's](entity:Customer) [card](entity:Card) to
            charge.

            If it is not specified, the subscriber receives an invoice via email
            with a link to pay for their subscription.
        timezone:
          type: string
          description: >-
            The timezone that is used in date calculations for the subscription.
            If unset, defaults to

            the location timezone. If a timezone is not configured for the
            location, defaults to "America/New_York".

            Format: the IANA Timezone Database identifier for the location
            timezone. For

            a list of time zones, see [List of tz database time
            zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
        source:
          $ref: '#/components/schemas/SubscriptionSource'
          description: The origination details of the subscription.
          x-release-status: BETA
        monthly_billing_anchor_date:
          type: integer
          description: The day-of-the-month to change the billing date to.
          minimum: 1
          maximum: 31
          x-release-status: BETA
        phases:
          type: array
          items:
            $ref: '#/components/schemas/Phase'
          description: array of phases for this subscription
      example:
        card_id: ccof:qy5x8hHGYsgLrp4Q4GB
        customer_id: CHFGVKYY8RSV93M5KCYTG4PN0G
        idempotency_key: 8193148c-9586-11e6-99f9-28cfe92138cf
        location_id: S8GWD5R9QB376
        phases:
          - order_template_id: U2NaowWxzXwpsZU697x7ZHOAnCNZY
            ordinal: 0
        plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
        source:
          name: My Application
        start_date: '2023-06-20'
        timezone: America/Los_Angeles
    CreateSubscriptionResponse:
      type: object
      description: >-
        Defines output parameters in a response from the

        [CreateSubscription](api-endpoint:Subscriptions-CreateSubscription)
        endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered during the request.
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: >-
            The newly created subscription.


            For more information, see

            [Subscription
            object](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions#subscription-object).
      example:
        subscription:
          card_id: ccof:qy5x8hHGYsgLrp4Q4GB
          created_at: '2023-06-20T21:53:10Z'
          customer_id: CHFGVKYY8RSV93M5KCYTG4PN0G
          id: 56214fb2-cc85-47a1-93bc-44f3766bb56f
          location_id: S8GWD5R9QB376
          phases:
            - order_template_id: U2NaowWxzXwpsZU697x7ZHOAnCNZY
              ordinal: 0
              plan_phase_uid: X2Q2AONPB3RB64Y27S25QCZP
              uid: 873451e0-745b-4e87-ab0b-c574933fe616
          plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
          source:
            name: My Application
          start_date: '2023-06-20'
          status: ACTIVE
          timezone: America/Los_Angeles
          version: 1
    CreateTeamMemberRequest:
      type: object
      description: Represents a create request for a `TeamMember` object.
      x-release-status: PUBLIC
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this `CreateTeamMember` request.

            Keys can be any valid string, but must be unique for every request.

            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).


            The minimum length is 1 and the maximum length is 45.
        team_member:
          $ref: '#/components/schemas/TeamMember'
          description: >-
            **Required** The data used to create the `TeamMember` object. If you
            include `wage_setting`, you must provide

            `job_id` for each job assignment. To get job IDs, call
            [ListJobs](api-endpoint:Team-ListJobs).
      example:
        idempotency_key: idempotency-key-0
        team_member:
          assigned_locations:
            assignment_type: EXPLICIT_LOCATIONS
            location_ids:
              - YSGH2WBKG94QZ
              - GA2Y9HSJ8KRYT
          email_address: joe_doe@gmail.com
          family_name: Doe
          given_name: Joe
          phone_number: '+14159283333'
          reference_id: reference_id_1
          status: ACTIVE
          wage_setting:
            is_overtime_exempt: true
            job_assignments:
              - annual_rate:
                  amount: 3000000
                  currency: USD
                job_id: FjS8x95cqHiMenw4f1NAUH4P
                pay_type: SALARY
                weekly_hours: 40
              - hourly_rate:
                  amount: 2000
                  currency: USD
                job_id: VDNpRv8da51NU8qZFC5zDWpF
                pay_type: HOURLY
    CreateTeamMemberResponse:
      type: object
      description: >-
        Represents a response from a create request containing the created
        `TeamMember` object or error messages.
      x-release-status: PUBLIC
      properties:
        team_member:
          $ref: '#/components/schemas/TeamMember'
          description: The successfully created `TeamMember` object.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: The errors that occurred during the request.
      example:
        team_member:
          assigned_locations:
            assignment_type: EXPLICIT_LOCATIONS
            location_ids:
              - GA2Y9HSJ8KRYT
              - YSGH2WBKG94QZ
          created_at: '2021-06-11T22:55:45Z'
          email_address: joe_doe@example.com
          family_name: Doe
          given_name: Joe
          id: 1yJlHapkseYnNPETIU1B
          is_owner: false
          phone_number: '+14159283333'
          reference_id: reference_id_1
          status: ACTIVE
          updated_at: '2021-06-11T22:55:45Z'
          wage_setting:
            created_at: '2021-06-11T22:55:45Z'
            is_overtime_exempt: true
            job_assignments:
              - annual_rate:
                  amount: 3000000
                  currency: USD
                hourly_rate:
                  amount: 1443
                  currency: USD
                job_id: FjS8x95cqHiMenw4f1NAUH4P
                job_title: Manager
                pay_type: SALARY
                weekly_hours: 40
              - hourly_rate:
                  amount: 2000
                  currency: USD
                job_id: VDNpRv8da51NU8qZFC5zDWpF
                job_title: Cashier
                pay_type: HOURLY
            team_member_id: 1yJlHapkseYnNPETIU1B
            updated_at: '2021-06-11T22:55:45Z'
            version: 1
    CreateTerminalActionRequest:
      type: object
      x-release-status: BETA
      required:
        - idempotency_key
        - action
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this `CreateAction` request. Keys
            can be any valid string

            but must be unique for every `CreateAction` request.


            See [Idempotency
            keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
            for more

            information.
          minLength: 1
          maxLength: 64
        action:
          $ref: '#/components/schemas/TerminalAction'
          description: The Action to create.
      example:
        action:
          deadline_duration: PT5M
          device_id: '{{DEVICE_ID}}'
          save_card_options:
            customer_id: '{{CUSTOMER_ID}}'
            reference_id: user-id-1
          type: SAVE_CARD
        idempotency_key: thahn-70e75c10-47f7-4ab6-88cc-aaa4076d065e
    CreateTerminalActionResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        action:
          $ref: '#/components/schemas/TerminalAction'
          description: The created `TerminalAction`
      example:
        action:
          app_id: APP_ID
          created_at: '2021-07-28T23:22:07.476Z'
          deadline_duration: PT5M
          device_id: DEVICE_ID
          id: termapia:jveJIAkkAjILHkdCE
          location_id: LOCATION_ID
          save_card_options:
            customer_id: CUSTOMER_ID
            reference_id: user-id-1
          status: PENDING
          type: SAVE_CARD
          updated_at: '2021-07-28T23:22:07.476Z'
    CreateTerminalCheckoutRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - idempotency_key
        - checkout
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this `CreateCheckout` request. Keys
            can be any valid string but

            must be unique for every `CreateCheckout` request.


            See [Idempotency
            keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
            for more information.
          minLength: 1
          maxLength: 64
        checkout:
          $ref: '#/components/schemas/TerminalCheckout'
          description: The checkout to create.
      example:
        checkout:
          amount_money:
            amount: 2610
            currency: USD
          device_options:
            device_id: dbb5d83a-7838-11ea-bc55-0242ac130003
          note: A brief note
          reference_id: id11572
        idempotency_key: 28a0c3bc-7839-11ea-bc55-0242ac130003
    CreateTerminalCheckoutResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        checkout:
          $ref: '#/components/schemas/TerminalCheckout'
          description: The created `TerminalCheckout`.
      example:
        checkout:
          amount_money:
            amount: 2610
            currency: USD
          app_id: APP_ID
          created_at: '2020-04-06T16:39:32.545Z'
          deadline_duration: PT5M
          device_options:
            device_id: dbb5d83a-7838-11ea-bc55-0242ac130003
            skip_receipt_screen: false
            tip_settings:
              allow_tipping: false
          id: 08YceKh7B3ZqO
          location_id: LOCATION_ID
          note: A brief note
          payment_type: CARD_PRESENT
          reference_id: id11572
          status: PENDING
          updated_at: '2020-04-06T16:39:32.545Z'
    CreateTerminalRefundRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - idempotency_key
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this `CreateRefund` request. Keys
            can be any valid string but

            must be unique for every `CreateRefund` request.


            See [Idempotency
            keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
            for more information.
          minLength: 1
          maxLength: 64
        refund:
          $ref: '#/components/schemas/TerminalRefund'
          description: The refund to create.
      example:
        idempotency_key: 402a640b-b26f-401f-b406-46f839590c04
        refund:
          amount_money:
            amount: 111
            currency: CAD
          device_id: f72dfb8e-4d65-4e56-aade-ec3fb8d33291
          payment_id: 5O5OvgkcNUhl7JBuINflcjKqUzXZY
          reason: Returning items
    CreateTerminalRefundResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        refund:
          $ref: '#/components/schemas/TerminalRefund'
          description: The created `TerminalRefund`.
      example:
        refund:
          amount_money:
            amount: 111
            currency: CAD
          app_id: sandbox-sq0idb-c2OuYt13YaCAeJq_2cd8OQ
          card:
            bin: '411111'
            card_brand: INTERAC
            card_type: CREDIT
            exp_month: 1
            exp_year: 2022
            fingerprint: >-
              sq-1-B1fP9MNNmZgVVaPKRND6oDKYbz25S2cTvg9Mzwg3RMTK1zT1PiGRT-AE3nTA8vSmmw
            last_4: '1111'
          created_at: '2020-09-29T15:21:46.771Z'
          deadline_duration: PT5M
          device_id: f72dfb8e-4d65-4e56-aade-ec3fb8d33291
          id: 009DP5HD-5O5OvgkcNUhl7JBuINflcjKqUzXZY
          location_id: 76C9W6K8CNNQ5
          order_id: kcuKDKreRaI4gF4TjmEgZjHk8Z7YY
          payment_id: 5O5OvgkcNUhl7JBuINflcjKqUzXZY
          reason: Returning items
          status: PENDING
          updated_at: '2020-09-29T15:21:46.771Z'
    CreateVendorRequest:
      type: object
      description: >-
        Represents an input to a call to
        [CreateVendor](api-endpoint:Vendors-CreateVendor).
      x-release-status: BETA
      required:
        - idempotency_key
      properties:
        idempotency_key:
          type: string
          description: >-
            A client-supplied, universally unique identifier (UUID) to make this
            [CreateVendor](api-endpoint:Vendors-CreateVendor) call idempotent.


            See
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
            in the

            [API Development
            101](https://developer.squareup.com/docs/buildbasics) section for
            more

            information.
          minLength: 1
          maxLength: 128
        vendor:
          $ref: '#/components/schemas/Vendor'
          description: The requested [Vendor](entity:Vendor) to be created.
      example:
        idempotency_key: 8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe
        vendor:
          account_number: '4025391'
          address:
            address_line_1: 505 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          contacts:
            - email_address: joe@joesfreshseafood.com
              name: Joe Burrow
              phone_number: 1-212-555-4250
          name: Joe's Fresh Seafood
          note: a vendor
    CreateVendorResponse:
      type: object
      description: >-
        Represents an output from a call to
        [CreateVendor](api-endpoint:Vendors-CreateVendor).
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered when the request fails.
        vendor:
          $ref: '#/components/schemas/Vendor'
          description: The successfully created [Vendor](entity:Vendor) object.
      example:
        vendor:
          account_number: '4025391'
          address:
            address_line_1: 505 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          contacts:
            - email_address: joe@joesfreshseafood.com
              id: INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A
              name: Joe Burrow
              phone_number: 1-212-555-4250
          created_at: '2022-03-16T10:21:54.859Z'
          id: INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4
          name: Joe's Fresh Seafood
          note: a vendor
          status: ACTIVE
          updated_at: '2022-03-16T10:21:54.859Z'
          version: 1
    CreateWebhookSubscriptionRequest:
      type: object
      description: Creates a [Subscription](entity:WebhookSubscription).
      x-release-status: PUBLIC
      required:
        - subscription
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies the
            [CreateWebhookSubscription](api-endpoint:WebhookSubscriptions-CreateWebhookSubscription)
            request.
          maxLength: 45
        subscription:
          $ref: '#/components/schemas/WebhookSubscription'
          description: The [Subscription](entity:WebhookSubscription) to create.
      example:
        idempotency_key: 63f84c6c-2200-4c99-846c-2670a1311fbf
        subscription:
          api_version: '2021-12-15'
          event_types:
            - payment.created
            - payment.updated
          name: Example Webhook Subscription
          notification_url: https://example-webhook-url.com
    CreateWebhookSubscriptionResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [CreateWebhookSubscription](api-endpoint:WebhookSubscriptions-CreateWebhookSubscription)
        endpoint.


        Note: if there are errors processing the request, the
        [Subscription](entity:WebhookSubscription) will not be

        present.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        subscription:
          $ref: '#/components/schemas/WebhookSubscription'
          description: The new [Subscription](entity:WebhookSubscription).
      example:
        subscription:
          api_version: '2021-12-15'
          created_at: 2022-01-10 23:29:48 +0000 UTC
          enabled: true
          event_types:
            - payment.created
            - payment.updated
          id: wbhk_b35f6b3145074cf9ad513610786c19d5
          name: Example Webhook Subscription
          notification_url: https://example-webhook-url.com
          signature_key: 1k9bIJKCeTmSQwyagtNRLg
          updated_at: 2022-01-10 23:29:48 +0000 UTC
    Currency:
      type: string
      enum:
        - UNKNOWN_CURRENCY
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BHD
        - BIF
        - BMD
        - BND
        - BOB
        - BOV
        - BRL
        - BSD
        - BTN
        - BWP
        - BYR
        - BZD
        - CAD
        - CDF
        - CHE
        - CHF
        - CHW
        - CLF
        - CLP
        - CNY
        - COP
        - COU
        - CRC
        - CUC
        - CUP
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ERN
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - INR
        - IQD
        - IRR
        - ISK
        - JMD
        - JOD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KPW
        - KRW
        - KWD
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - LTL
        - LVL
        - LYD
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MRO
        - MUR
        - MVR
        - MWK
        - MXN
        - MXV
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - OMR
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SDG
        - SEK
        - SGD
        - SHP
        - SLL
        - SLE
        - SOS
        - SRD
        - SSP
        - STD
        - SVC
        - SYP
        - SZL
        - THB
        - TJS
        - TMT
        - TND
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - USN
        - USS
        - UYI
        - UYU
        - UZS
        - VEF
        - VND
        - VUV
        - WST
        - XAF
        - XAG
        - XAU
        - XBA
        - XBB
        - XBC
        - XBD
        - XCD
        - XDR
        - XOF
        - XPD
        - XPF
        - XPT
        - XTS
        - XXX
        - YER
        - ZAR
        - ZMK
        - ZMW
        - BTC
        - XUS
      x-enum-elements:
        - name: UNKNOWN_CURRENCY
          description: Unknown currency
        - name: AED
          description: United Arab Emirates dirham
        - name: AFN
          description: Afghan afghani
        - name: ALL
          description: Albanian lek
        - name: AMD
          description: Armenian dram
        - name: ANG
          description: Netherlands Antillean guilder
        - name: AOA
          description: Angolan kwanza
        - name: ARS
          description: Argentine peso
        - name: AUD
          description: Australian dollar
        - name: AWG
          description: Aruban florin
        - name: AZN
          description: Azerbaijani manat
        - name: BAM
          description: Bosnia and Herzegovina convertible mark
        - name: BBD
          description: Barbados dollar
        - name: BDT
          description: Bangladeshi taka
        - name: BGN
          description: Bulgarian lev
        - name: BHD
          description: Bahraini dinar
        - name: BIF
          description: Burundian franc
        - name: BMD
          description: Bermudian dollar
        - name: BND
          description: Brunei dollar
        - name: BOB
          description: Boliviano
        - name: BOV
          description: Bolivian Mvdol
        - name: BRL
          description: Brazilian real
        - name: BSD
          description: Bahamian dollar
        - name: BTN
          description: Bhutanese ngultrum
        - name: BWP
          description: Botswana pula
        - name: BYR
          description: Belarusian ruble
        - name: BZD
          description: Belize dollar
        - name: CAD
          description: Canadian dollar
        - name: CDF
          description: Congolese franc
        - name: CHE
          description: WIR Euro
        - name: CHF
          description: Swiss franc
        - name: CHW
          description: WIR Franc
        - name: CLF
          description: Unidad de Fomento
        - name: CLP
          description: Chilean peso
        - name: CNY
          description: Chinese yuan
        - name: COP
          description: Colombian peso
        - name: COU
          description: Unidad de Valor Real
        - name: CRC
          description: Costa Rican colon
        - name: CUC
          description: Cuban convertible peso
        - name: CUP
          description: Cuban peso
        - name: CVE
          description: Cape Verdean escudo
        - name: CZK
          description: Czech koruna
        - name: DJF
          description: Djiboutian franc
        - name: DKK
          description: Danish krone
        - name: DOP
          description: Dominican peso
        - name: DZD
          description: Algerian dinar
        - name: EGP
          description: Egyptian pound
        - name: ERN
          description: Eritrean nakfa
        - name: ETB
          description: Ethiopian birr
        - name: EUR
          description: Euro
        - name: FJD
          description: Fiji dollar
        - name: FKP
          description: Falkland Islands pound
        - name: GBP
          description: Pound sterling
        - name: GEL
          description: Georgian lari
        - name: GHS
          description: Ghanaian cedi
        - name: GIP
          description: Gibraltar pound
        - name: GMD
          description: Gambian dalasi
        - name: GNF
          description: Guinean franc
        - name: GTQ
          description: Guatemalan quetzal
        - name: GYD
          description: Guyanese dollar
        - name: HKD
          description: Hong Kong dollar
        - name: HNL
          description: Honduran lempira
        - name: HRK
          description: Croatian kuna
        - name: HTG
          description: Haitian gourde
        - name: HUF
          description: Hungarian forint
        - name: IDR
          description: Indonesian rupiah
        - name: ILS
          description: Israeli new shekel
        - name: INR
          description: Indian rupee
        - name: IQD
          description: Iraqi dinar
        - name: IRR
          description: Iranian rial
        - name: ISK
          description: Icelandic kr�na
        - name: JMD
          description: Jamaican dollar
        - name: JOD
          description: Jordanian dinar
        - name: JPY
          description: Japanese yen
        - name: KES
          description: Kenyan shilling
        - name: KGS
          description: Kyrgyzstani som
        - name: KHR
          description: Cambodian riel
        - name: KMF
          description: Comoro franc
        - name: KPW
          description: North Korean won
        - name: KRW
          description: South Korean won
        - name: KWD
          description: Kuwaiti dinar
        - name: KYD
          description: Cayman Islands dollar
        - name: KZT
          description: Kazakhstani tenge
        - name: LAK
          description: Lao kip
        - name: LBP
          description: Lebanese pound
        - name: LKR
          description: Sri Lankan rupee
        - name: LRD
          description: Liberian dollar
        - name: LSL
          description: Lesotho loti
        - name: LTL
          description: Lithuanian litas
        - name: LVL
          description: Latvian lats
        - name: LYD
          description: Libyan dinar
        - name: MAD
          description: Moroccan dirham
        - name: MDL
          description: Moldovan leu
        - name: MGA
          description: Malagasy ariary
        - name: MKD
          description: Macedonian denar
        - name: MMK
          description: Myanmar kyat
        - name: MNT
          description: Mongolian t�gr�g
        - name: MOP
          description: Macanese pataca
        - name: MRO
          description: Mauritanian ouguiya
        - name: MUR
          description: Mauritian rupee
        - name: MVR
          description: Maldivian rufiyaa
        - name: MWK
          description: Malawian kwacha
        - name: MXN
          description: Mexican peso
        - name: MXV
          description: Mexican Unidad de Inversion
        - name: MYR
          description: Malaysian ringgit
        - name: MZN
          description: Mozambican metical
        - name: NAD
          description: Namibian dollar
        - name: NGN
          description: Nigerian naira
        - name: NIO
          description: Nicaraguan c�rdoba
        - name: NOK
          description: Norwegian krone
        - name: NPR
          description: Nepalese rupee
        - name: NZD
          description: New Zealand dollar
        - name: OMR
          description: Omani rial
        - name: PAB
          description: Panamanian balboa
        - name: PEN
          description: Peruvian sol
        - name: PGK
          description: Papua New Guinean kina
        - name: PHP
          description: Philippine peso
        - name: PKR
          description: Pakistani rupee
        - name: PLN
          description: Polish zBoty
        - name: PYG
          description: Paraguayan guaran�
        - name: QAR
          description: Qatari riyal
        - name: RON
          description: Romanian leu
        - name: RSD
          description: Serbian dinar
        - name: RUB
          description: Russian ruble
        - name: RWF
          description: Rwandan franc
        - name: SAR
          description: Saudi riyal
        - name: SBD
          description: Solomon Islands dollar
        - name: SCR
          description: Seychelles rupee
        - name: SDG
          description: Sudanese pound
        - name: SEK
          description: Swedish krona
        - name: SGD
          description: Singapore dollar
        - name: SHP
          description: Saint Helena pound
        - name: SLL
          description: Sierra Leonean first leone
        - name: SLE
          description: Sierra Leonean second leone
        - name: SOS
          description: Somali shilling
        - name: SRD
          description: Surinamese dollar
        - name: SSP
          description: South Sudanese pound
        - name: STD
          description: S�o Tom� and Pr�ncipe dobra
        - name: SVC
          description: Salvadoran col�n
        - name: SYP
          description: Syrian pound
        - name: SZL
          description: Swazi lilangeni
        - name: THB
          description: Thai baht
        - name: TJS
          description: Tajikstani somoni
        - name: TMT
          description: Turkmenistan manat
        - name: TND
          description: Tunisian dinar
        - name: TOP
          description: Tongan pa'anga
        - name: TRY
          description: Turkish lira
        - name: TTD
          description: Trinidad and Tobago dollar
        - name: TWD
          description: New Taiwan dollar
        - name: TZS
          description: Tanzanian shilling
        - name: UAH
          description: Ukrainian hryvnia
        - name: UGX
          description: Ugandan shilling
        - name: USD
          description: United States dollar
        - name: USN
          description: United States dollar (next day)
        - name: USS
          description: United States dollar (same day)
        - name: UYI
          description: Uruguay Peso en Unidedades Indexadas
        - name: UYU
          description: Uruguyan peso
        - name: UZS
          description: Uzbekistan som
        - name: VEF
          description: Venezuelan bol�var soberano
        - name: VND
          description: Vietnamese �ng
        - name: VUV
          description: Vanuatu vatu
        - name: WST
          description: Samoan tala
        - name: XAF
          description: CFA franc BEAC
        - name: XAG
          description: Silver
        - name: XAU
          description: Gold
        - name: XBA
          description: European Composite Unit
        - name: XBB
          description: European Monetary Unit
        - name: XBC
          description: European Unit of Account 9
        - name: XBD
          description: European Unit of Account 17
        - name: XCD
          description: East Caribbean dollar
        - name: XDR
          description: Special drawing rights (International Monetary Fund)
        - name: XOF
          description: CFA franc BCEAO
        - name: XPD
          description: Palladium
        - name: XPF
          description: CFP franc
        - name: XPT
          description: Platinum
        - name: XTS
          description: Code reserved for testing
        - name: XXX
          description: No currency
        - name: YER
          description: Yemeni rial
        - name: ZAR
          description: South African rand
        - name: ZMK
          description: Zambian kwacha
        - name: ZMW
          description: Zambian kwacha
        - name: BTC
          description: Bitcoin
        - name: XUS
          description: USD Coin
      description: >-
        Indicates the associated currency for an amount of money. Values
        correspond

        to [ISO 4217](https://wikipedia.org/wiki/ISO_4217).
      x-release-status: PUBLIC
    CustomAttribute:
      type: object
      description: >-
        A custom attribute value. Each custom attribute value has a
        corresponding

        `CustomAttributeDefinition` object.
      x-release-status: PUBLIC
      properties:
        key:
          type: string
          description: >-
            The identifier

            of the custom attribute definition and its corresponding custom
            attributes. This value

            can be a simple key, which is the key that is provided when the
            custom attribute definition

            is created, or a qualified key, if the requesting

            application is not the definition owner. The qualified key consists
            of the application ID

            of the custom attribute definition owner

            followed by the simple key that was provided when the definition was
            created. It has the

            format application_id:simple key.


            The value for a simple key can contain up to 60 alphanumeric
            characters, periods (.),

            underscores (_), and hyphens (-).
          minLength: 1
          pattern: ^([a-zA-Z0-9\._-]+:)?[a-zA-Z0-9\._-]{1,60}$
          nullable: true
        value:
          description: >-
            The value assigned to the custom attribute. It is validated against
            the custom

            attribute definition's schema on write operations. For more
            information about custom

            attribute values,

            see [Custom Attributes
            Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).
          nullable: true
        version:
          type: integer
          description: >-
            Read only. The current version of the custom attribute. This field
            is incremented when the custom attribute is changed.

            When updating an existing custom attribute value, you can provide
            this field

            and specify the current version of the custom attribute to enable

            [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).

            This field can also be used to enforce strong consistency for reads.
            For more information about strong consistency for reads,

            see [Custom Attributes
            Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).
        visibility:
          $ref: '#/components/schemas/CustomAttributeDefinitionVisibility'
          description: >-
            A copy of the `visibility` field value for the associated custom
            attribute definition.

            See
            [CustomAttributeDefinitionVisibility](#type-customattributedefinitionvisibility)
            for possible values
          readOnly: true
        definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            A copy of the associated custom attribute definition object. This
            field is only set when

            the optional field is specified on the request.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp that indicates when the custom attribute was created
            or was most recently

            updated, in RFC 3339 format.
          readOnly: true
        created_at:
          type: string
          description: >-
            The timestamp that indicates when the custom attribute was created,
            in RFC 3339 format.
          readOnly: true
    CustomAttributeDefinition:
      type: object
      description: >-
        Represents a definition for custom attribute values. A custom attribute
        definition

        specifies the key, visibility, schema, and other properties for a custom
        attribute.
      x-release-status: PUBLIC
      properties:
        key:
          type: string
          description: >-
            The identifier

            of the custom attribute definition and its corresponding custom
            attributes. This value

            can be a simple key, which is the key that is provided when the
            custom attribute definition

            is created, or a qualified key, if the requesting

            application is not the definition owner. The qualified key consists
            of the application ID

            of the custom attribute definition owner

            followed by the simple key that was provided when the definition was
            created. It has the

            format application_id:simple key.


            The value for a simple key can contain up to 60 alphanumeric
            characters, periods (.),

            underscores (_), and hyphens (-).


            This field can not be changed

            after the custom attribute definition is created. This field is
            required when creating

            a definition and must be unique per application, seller, and
            resource type.
          minLength: 1
          pattern: ^([a-zA-Z0-9\._-]+:)?[a-zA-Z0-9\._-]{1,60}$
          nullable: true
        schema:
          type: object
          description: >-
            The JSON schema for the custom attribute definition, which
            determines the data type of the corresponding custom attributes. For
            more information,

            see [Custom Attributes
            Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).
            This field is required when creating a definition.
          nullable: true
        name:
          type: string
          description: >-
            The name of the custom attribute definition for API and
            seller-facing UI purposes. The name must

            be unique within the seller and application pair. This field is
            required if the

            `visibility` field is `VISIBILITY_READ_ONLY` or
            `VISIBILITY_READ_WRITE_VALUES`.
          maxLength: 255
          nullable: true
        description:
          type: string
          description: >-
            Seller-oriented description of the custom attribute definition,
            including any constraints

            that the seller should observe. May be displayed as a tooltip in
            Square UIs. This field is

            required if the `visibility` field is `VISIBILITY_READ_ONLY` or
            `VISIBILITY_READ_WRITE_VALUES`.
          maxLength: 255
          nullable: true
        visibility:
          $ref: '#/components/schemas/CustomAttributeDefinitionVisibility'
          description: >-
            Specifies how the custom attribute definition and its values should
            be shared with

            the seller and other applications. If no value is specified, the
            value defaults to `VISIBILITY_HIDDEN`.

            See [Visibility](#type-visibility) for possible values
          nullable: true
        version:
          type: integer
          description: >-
            Read only. The current version of the custom attribute definition.

            The value is incremented each time the custom attribute definition
            is updated.

            When updating a custom attribute definition, you can provide this
            field

            and specify the current version of the custom attribute definition
            to enable

            [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency).


            On writes, this field must be set to the latest version. Stale
            writes are rejected.


            This field can also be used to enforce strong consistency for reads.
            For more information about strong consistency for reads,

            see [Custom Attributes
            Overview](https://developer.squareup.com/docs/devtools/customattributes/overview).
        updated_at:
          type: string
          description: >-
            The timestamp that indicates when the custom attribute definition
            was created or most recently updated,

            in RFC 3339 format.
          readOnly: true
        created_at:
          type: string
          description: >-
            The timestamp that indicates when the custom attribute definition
            was created, in RFC 3339 format.
          readOnly: true
    CustomAttributeDefinitionVisibility:
      type: string
      enum:
        - VISIBILITY_HIDDEN
        - VISIBILITY_READ_ONLY
        - VISIBILITY_READ_WRITE_VALUES
      x-enum-elements:
        - name: VISIBILITY_HIDDEN
          description: >-
            The custom attribute definition and values are hidden from the
            seller (except on export

            of all seller data) and other developers.
        - name: VISIBILITY_READ_ONLY
          description: >-
            The seller and other developers can read the custom attribute
            definition and values

            on resources.
        - name: VISIBILITY_READ_WRITE_VALUES
          description: >-
            The seller and other developers can read the custom attribute
            definition,

            and can read and write values on resources. A custom attribute
            definition

            can only be edited or deleted by the application that created it.
      description: >-
        The level of permission that a seller or other applications requires to

        view this custom attribute definition.

        The `Visibility` field controls who can read and write the custom
        attribute values

        and custom attribute definition.
      x-release-status: PUBLIC
    CustomAttributeFilter:
      type: object
      description: |-
        Supported custom attribute query expressions for calling the
        [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems)
        endpoint to search for items or item variations.
      x-release-status: PUBLIC
      properties:
        custom_attribute_definition_id:
          type: string
          description: >-
            A query expression to filter items or item variations by matching
            their custom attributes'

            `custom_attribute_definition_id` property value against the the
            specified id.

            Exactly one of `custom_attribute_definition_id` or `key` must be
            specified.
          nullable: true
        key:
          type: string
          description: >-
            A query expression to filter items or item variations by matching
            their custom attributes'

            `key` property value against the specified key.

            Exactly one of `custom_attribute_definition_id` or `key` must be
            specified.
          nullable: true
        string_filter:
          type: string
          description: >-
            A query expression to filter items or item variations by matching
            their custom attributes'

            `string_value`  property value against the specified text.

            Exactly one of `string_filter`, `number_filter`,
            `selection_uids_filter`, or `bool_filter` must be specified.
          nullable: true
        number_filter:
          $ref: '#/components/schemas/Range'
          description: >-
            A query expression to filter items or item variations with their
            custom attributes

            containing a number value within the specified range.

            Exactly one of `string_filter`, `number_filter`,
            `selection_uids_filter`, or `bool_filter` must be specified.
          nullable: true
        selection_uids_filter:
          type: array
          items:
            type: string
          description: >-
            A query expression to filter items or item variations by matching 
            their custom attributes'

            `selection_uid_values` values against the specified selection uids.

            Exactly one of `string_filter`, `number_filter`,
            `selection_uids_filter`, or `bool_filter` must be specified.
          nullable: true
        bool_filter:
          type: boolean
          description: >-
            A query expression to filter items or item variations by matching
            their custom attributes'

            `boolean_value` property values against the specified Boolean
            expression.

            Exactly one of `string_filter`, `number_filter`,
            `selection_uids_filter`, or `bool_filter` must be specified.
          nullable: true
    CustomField:
      type: object
      description: >-
        Describes a custom form field to add to the checkout page to collect
        more information from buyers during checkout.

        For more information,

        see [Specify checkout
        options](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations#specify-checkout-options-1).
      x-release-status: PUBLIC
      required:
        - title
      properties:
        title:
          type: string
          description: The title of the custom field.
          minLength: 1
          maxLength: 50
    Customer:
      type: object
      description: >-
        Represents a Square customer profile in the Customer Directory of a
        Square seller.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: >-
            A unique Square-assigned ID for the customer profile.


            If you need this ID for an API request, use the ID returned when you
            created the customer profile or call the
            [SearchCustomers](api-endpoint:Customers-SearchCustomers) 

            or [ListCustomers](api-endpoint:Customers-ListCustomers) endpoint.
        created_at:
          type: string
          description: >-
            The timestamp when the customer profile was created, in RFC 3339
            format.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp when the customer profile was last updated, in RFC
            3339 format.
          readOnly: true
        given_name:
          type: string
          description: >-
            The given name (that is, the first name) associated with the
            customer profile.
          nullable: true
        family_name:
          type: string
          description: >-
            The family name (that is, the last name) associated with the
            customer profile.
          nullable: true
        nickname:
          type: string
          description: A nickname for the customer profile.
          nullable: true
        company_name:
          type: string
          description: A business name associated with the customer profile.
          nullable: true
        email_address:
          type: string
          description: The email address associated with the customer profile.
          nullable: true
        address:
          $ref: '#/components/schemas/Address'
          description: The physical address associated with the customer profile.
          nullable: true
        phone_number:
          type: string
          description: The phone number associated with the customer profile.
          nullable: true
        birthday:
          type: string
          description: >-
            The birthday associated with the customer profile, in `YYYY-MM-DD`
            format. For example, `1998-09-21`

            represents September 21, 1998, and `0000-09-21` represents September
            21 (without a birth year).
          nullable: true
        reference_id:
          type: string
          description: |-
            An optional second ID used to associate the customer profile with an
            entity in another system.
          nullable: true
        note:
          type: string
          description: A custom note associated with the customer profile.
          nullable: true
        preferences:
          $ref: '#/components/schemas/CustomerPreferences'
          description: Represents general customer preferences.
          nullable: true
        creation_source:
          $ref: '#/components/schemas/CustomerCreationSource'
          description: >-
            The method used to create the customer profile.

            See [CustomerCreationSource](#type-customercreationsource) for
            possible values
          nullable: true
        group_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of [customer groups](entity:CustomerGroup) the customer
            belongs to.
          nullable: true
        segment_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of [customer segments](entity:CustomerSegment) the customer
            belongs to.
          nullable: true
        version:
          type: integer
          description: >-
            The Square-assigned version number of the customer profile. The
            version number is incremented each time an update is committed to
            the customer profile, except for changes to customer segment
            membership.
          format: int64
        tax_ids:
          $ref: '#/components/schemas/CustomerTaxIds'
          description: >-
            The tax ID associated with the customer profile. This field is
            present only for customers of sellers in EU countries or the United
            Kingdom. 

            For more information, see [Customer tax
            IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids).
          nullable: true
    CustomerAddressFilter:
      type: object
      description: >-
        The customer address filter. This filter is used in a
        [CustomerCustomAttributeFilterValue](entity:CustomerCustomAttributeFilterValue)
        filter when

        searching by an `Address`-type custom attribute.
      x-release-status: PUBLIC
      properties:
        postal_code:
          $ref: '#/components/schemas/CustomerTextFilter'
          description: The postal code to search for. Only an `exact` match is supported.
          nullable: true
        country:
          $ref: '#/components/schemas/Country'
          description: |-
            The country code to search for.
            See [Country](#type-country) for possible values
          nullable: true
    CustomerCreationSource:
      type: string
      enum:
        - OTHER
        - APPOINTMENTS
        - COUPON
        - DELETION_RECOVERY
        - DIRECTORY
        - EGIFTING
        - EMAIL_COLLECTION
        - FEEDBACK
        - IMPORT
        - INVOICES
        - LOYALTY
        - MARKETING
        - MERGE
        - ONLINE_STORE
        - INSTANT_PROFILE
        - TERMINAL
        - THIRD_PARTY
        - THIRD_PARTY_IMPORT
        - UNMERGE_RECOVERY
      x-enum-elements:
        - name: OTHER
          description: >-
            The default creation source. This source is typically used for
            backward/future

            compatibility when the original source of a customer profile is

            unrecognized. For example, when older clients do not support newer

            source types.
        - name: APPOINTMENTS
          description: |-
            The customer profile was created automatically when an appointment
            was scheduled.
        - name: COUPON
          description: >-
            The customer profile was created automatically when a coupon was
            issued

            using Square Point of Sale.
        - name: DELETION_RECOVERY
          description: |-
            The customer profile was restored through Square's deletion recovery
            process.
        - name: DIRECTORY
          description: >-
            The customer profile was created manually through Square Seller
            Dashboard or the 

            Point of Sale application.
        - name: EGIFTING
          description: |-
            The customer profile was created automatically when a gift card was
            issued using Square Point of Sale. Customer profiles are created for
            both the buyer and the recipient of the gift card.
        - name: EMAIL_COLLECTION
          description: |-
            The customer profile was created through Square Point of Sale when
            signing up for marketing emails during checkout.
        - name: FEEDBACK
          description: >-
            The customer profile was created automatically when providing
            feedback

            through a digital receipt.
        - name: IMPORT
          description: >-
            The customer profile was created automatically when importing
            customer

            data through Square Seller Dashboard.
        - name: INVOICES
          description: >-
            The customer profile was created automatically during an invoice
            payment.
        - name: LOYALTY
          description: >-
            The customer profile was created automatically when customers
            provide a

            phone number for loyalty reward programs during checkout.
        - name: MARKETING
          description: |-
            The customer profile was created as the result of a campaign managed
            through Squares Facebook integration.
        - name: MERGE
          description: >-
            The customer profile was created as the result of explicitly merging

            multiple customer profiles through the Square Seller Dashboard or
            the Point of

            Sale application.
        - name: ONLINE_STORE
          description: >-
            The customer profile was created through Square's Online Store
            solution

            (legacy service).
        - name: INSTANT_PROFILE
          description: >-
            The customer profile was created automatically as the result of a
            successful

            transaction that did not explicitly link to an existing customer
            profile.
        - name: TERMINAL
          description: The customer profile was created through Square's Virtual Terminal.
        - name: THIRD_PARTY
          description: The customer profile was created through a Square API call.
        - name: THIRD_PARTY_IMPORT
          description: >-
            The customer profile was created by a third-party product and
            imported

            through an official integration.
        - name: UNMERGE_RECOVERY
          description: |-
            The customer profile was restored through Square's unmerge recovery
            process.
      description: Indicates the method used to create the customer profile.
      x-release-status: PUBLIC
    CustomerCreationSourceFilter:
      type: object
      description: >-
        The creation source filter.


        If one or more creation sources are set, customer profiles are included
        in,

        or excluded from, the result if they match at least one of the filter
        criteria.
      x-release-status: PUBLIC
      properties:
        values:
          type: array
          items:
            $ref: '#/components/schemas/CustomerCreationSource'
          description: >-
            The list of creation sources used as filtering criteria.

            See [CustomerCreationSource](#type-customercreationsource) for
            possible values
          nullable: true
        rule:
          $ref: '#/components/schemas/CustomerInclusionExclusion'
          description: >-
            Indicates whether a customer profile matching the filter criteria

            should be included in the result or excluded from the result.


            Default: `INCLUDE`.

            See [CustomerInclusionExclusion](#type-customerinclusionexclusion)
            for possible values
          nullable: true
    CustomerCustomAttributeFilter:
      type: object
      description: >-
        The custom attribute filter. Use this filter in a set of [custom
        attribute filters](entity:CustomerCustomAttributeFilters) to search

        based on the value or last updated date of a customer-related [custom
        attribute](entity:CustomAttribute).
      x-release-status: PUBLIC
      required:
        - key
      properties:
        key:
          type: string
          description: >-
            The `key` of the [custom attribute](entity:CustomAttribute) to
            filter by. The key is the identifier of the custom attribute

            (and the corresponding custom attribute definition) and can be
            retrieved using the [Customer Custom Attributes
            API](api:CustomerCustomAttributes).
        filter:
          $ref: '#/components/schemas/CustomerCustomAttributeFilterValue'
          description: >-
            A filter that corresponds to the data type of the target custom
            attribute. For example, provide the `phone` filter to

            search based on the value of a `PhoneNumber`-type custom attribute.
            The data type is specified by the schema field of the custom
            attribute definition,

            which can be retrieved using the [Customer Custom Attributes
            API](api:CustomerCustomAttributes).


            You must provide this `filter` field, the `updated_at` field, or
            both.
          nullable: true
        updated_at:
          $ref: '#/components/schemas/TimeRange'
          description: >-
            The date range for when the custom attribute was last updated. The
            date range can include `start_at`, `end_at`, or

            both. Range boundaries are inclusive. Dates are specified as RFC
            3339 timestamps.


            You must provide this `updated_at` field, the `filter` field, or
            both.
    CustomerCustomAttributeFilterValue:
      type: object
      description: >-
        A type-specific filter used in a [custom attribute
        filter](entity:CustomerCustomAttributeFilter) to search based on the
        value 

        of a customer-related [custom attribute](entity:CustomAttribute).
      x-release-status: PUBLIC
      properties:
        email:
          $ref: '#/components/schemas/CustomerTextFilter'
          description: >-
            A filter for a query based on the value of an `Email`-type custom
            attribute. This filter is case-insensitive and can

            include `exact` or `fuzzy`, but not both.


            For an `exact` match, provide the complete email address.


            For a `fuzzy` match, provide a query expression containing one or
            more query tokens to match against the email address. Square removes

            any punctuation (including periods (.), underscores (_), and the @
            symbol) and tokenizes the email addresses on spaces. A match is
            found

            if a tokenized email address contains all the tokens in the search
            query, irrespective of the token order. For example, `Steven gmail`

            matches steven.jones@gmail.com and mygmail@stevensbakery.com.
          nullable: true
        phone:
          $ref: '#/components/schemas/CustomerTextFilter'
          description: >-
            A filter for a query based on the value of a `PhoneNumber`-type
            custom attribute. This filter is case-insensitive and

            can include `exact` or `fuzzy`, but not both.


            For an `exact` match, provide the complete phone number. This is
            always an E.164-compliant phone number that starts

            with the + sign followed by the country code and subscriber number.
            For example, the format for a US phone number is +12061112222.


            For a `fuzzy` match, provide a query expression containing one or
            more query tokens to match against the phone number.

            Square removes any punctuation and tokenizes the expression on
            spaces. A match is found if a tokenized phone number contains

            all the tokens in the search query, irrespective of the token order.
            For example, `415 123 45` is tokenized to `415`, `123`, and `45`,

            which matches +14151234567 and +12345674158, but does not match
            +1234156780. Similarly, the expression `415` matches

            +14151234567, +12345674158, and +1234156780.
          nullable: true
        text:
          $ref: '#/components/schemas/CustomerTextFilter'
          description: >-
            A filter for a query based on the value of a `String`-type custom
            attribute. This filter is case-insensitive and 

            can include `exact` or `fuzzy`, but not both.


            For an `exact` match, provide the complete string.


            For a `fuzzy` match, provide a query expression containing one or
            more query tokens in any order that contain complete words

            to match against the string. Square tokenizes the expression using a
            grammar-based tokenizer. For example, the expressions `quick brown`,

            `brown quick`, and `quick fox` match "The quick brown fox jumps over
            the lazy dog". However, `quick foxes` and `qui` do not match.
          nullable: true
        selection:
          $ref: '#/components/schemas/FilterValue'
          description: >-
            A filter for a query based on the display name for a
            `Selection`-type custom attribute value. This filter is
            case-sensitive

            and can contain `any`, `all`, or both. The `none` condition is not
            supported.


            Provide the display name of each item that you want to search for.
            To find the display names for the selection, use the 

            [Customer Custom Attributes API](api:CustomerCustomAttributes) to
            retrieve the corresponding custom attribute definition

            and then check the `schema.items.names` field. For more information,
            see

            [Search based on
            selection](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#custom-attribute-value-filter-selection).


            Note that when a `Selection`-type custom attribute is assigned to a
            customer profile, the custom attribute value is a list of one

            or more UUIDs (sourced from the `schema.items.enum` field) that map
            to the item names. These UUIDs are unique per seller.
          nullable: true
        date:
          $ref: '#/components/schemas/TimeRange'
          description: >-
            A filter for a query based on the value of a `Date`-type custom
            attribute.


            Provide a date range for this filter using `start_at`, `end_at`, or
            both. Range boundaries are inclusive. Dates can be specified

            in `YYYY-MM-DD` format or as RFC 3339 timestamps.
          nullable: true
        number:
          $ref: '#/components/schemas/FloatNumberRange'
          description: >-
            A filter for a query based on the value of a `Number`-type custom
            attribute, which can be an integer or a decimal with up to

            5 digits of precision.


            Provide a numerical range for this filter using `start_at`,
            `end_at`, or both. Range boundaries are inclusive. Numbers are
            specified

            as decimals or integers. The absolute value of range boundaries must
            not exceed `(2^63-1)/10^5`, or 92233720368547.
          nullable: true
        boolean:
          type: boolean
          description: >-
            A filter for a query based on the value of a `Boolean`-type custom
            attribute.
          nullable: true
        address:
          $ref: '#/components/schemas/CustomerAddressFilter'
          description: >-
            A filter for a query based on the value of an `Address`-type custom
            attribute. The filter can include `postal_code`, `country`, or both.
          nullable: true
    CustomerCustomAttributeFilters:
      type: object
      description: >-
        The custom attribute filters in a set of [customer
        filters](entity:CustomerFilter) used in a search query. Use this filter

        to search based on [custom attributes](entity:CustomAttribute) that are
        assigned to customer profiles. For more information, see

        [Search by custom
        attribute](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-custom-attribute).
      x-release-status: PUBLIC
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/CustomerCustomAttributeFilter'
          description: >-
            The custom attribute filters. Each filter must specify `key` and
            include the `filter` field with a type-specific filter,

            the `updated_at` field, or both. The provided keys must be unique
            within the list of custom attribute filters.
          nullable: true
    CustomerDetails:
      type: object
      description: Details about the customer making the payment.
      x-release-status: PUBLIC
      properties:
        customer_initiated:
          type: boolean
          description: Indicates whether the customer initiated the payment.
          nullable: true
        seller_keyed_in:
          type: boolean
          description: >-
            Indicates that the seller keyed in payment details on behalf of the
            customer.

            This is used to flag a payment as Mail Order / Telephone Order
            (MOTO).
          nullable: true
    CustomerFilter:
      type: object
      description: >-
        Represents the filtering criteria in a [search
        query](entity:CustomerQuery) that defines how to filter

        customer profiles returned in
        [SearchCustomers](api-endpoint:Customers-SearchCustomers) results.
      x-release-status: PUBLIC
      properties:
        creation_source:
          $ref: '#/components/schemas/CustomerCreationSourceFilter'
          description: A filter to select customers based on their creation source.
          nullable: true
        created_at:
          $ref: '#/components/schemas/TimeRange'
          description: A filter to select customers based on when they were created.
        updated_at:
          $ref: '#/components/schemas/TimeRange'
          description: A filter to select customers based on when they were last updated.
        email_address:
          $ref: '#/components/schemas/CustomerTextFilter'
          description: >-
            A filter to [select customers by their email
            address](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-email-address) 

            visible to the seller. 

            This filter is case-insensitive.


            For [exact
            matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#exact-search-by-email-address),
            this

            filter causes the search to return customer profiles 

            whose `email_address` field value are identical to the email address
            provided

            in the query.


            For [fuzzy
            matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#fuzzy-search-by-email-address), 

            this filter causes the search to return customer profiles 

            whose `email_address` field value has a token-wise partial match
            against the filtering 

            expression in the query. For example, with `Steven gmail` provided
            in a search

            query, the search returns customers whose email address is
            `steven.johnson@gmail.com` 

            or `mygmail@stevensbakery.com`. Square removes any punctuation
            (including periods (.),

            underscores (_), and the @ symbol) and tokenizes the email addresses
            on spaces. A match is

            found if a tokenized email address contains all the tokens in the
            search query, 

            irrespective of the token order.
          nullable: true
        phone_number:
          $ref: '#/components/schemas/CustomerTextFilter'
          description: >-
            A filter to [select customers by their phone
            numbers](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-phone-number)

            visible to the seller.


            For [exact
            matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#exact-search-by-phone-number),

            this filter returns customers whose phone number matches the
            specified query expression. The number in the query must be of an

            E.164-compliant form. In particular, it must include the leading `+`
            sign followed by a country code and then a subscriber number.

            For example, the standard E.164 form of a US phone number is
            `+12062223333` and an E.164-compliant variation is `+1 (206)
            222-3333`.

            To match the query expression, stored customer phone numbers are
            converted to the standard E.164 form.


            For [fuzzy
            matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#fuzzy-search-by-phone-number),

            this filter returns customers whose phone number matches the token
            or tokens provided in the query expression. For example, with `415`

            provided in a search query, the search returns customers with the
            phone numbers `+1-415-212-1200`, `+1-212-415-1234`, and `+1 (551)
            234-1567`.

            Similarly, a search query of `415 123` returns customers with the
            phone numbers `+1-212-415-1234` and `+1 (551) 234-1567` but not

            `+1-212-415-1200`. A match is found if a tokenized phone number
            contains all the tokens in the search query, irrespective of the
            token order.
          nullable: true
        reference_id:
          $ref: '#/components/schemas/CustomerTextFilter'
          description: >-
            A filter to [select customers by their reference
            IDs](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-reference-id).

            This filter is case-insensitive.


            [Exact
            matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#exact-search-by-reference-id) 

            of a customer's reference ID against a query's reference ID is
            evaluated as an

            exact match between two strings, character by character in the given
            order.


            [Fuzzy
            matching](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#fuzzy-search-by-reference-id) 

            of stored reference IDs against queried reference IDs works 

            exactly the same as fuzzy matching on email addresses.
            Non-alphanumeric characters 

            are replaced by spaces to tokenize stored and queried reference IDs.
            A match is found

            if a tokenized stored reference ID contains all tokens specified in
            any order in the query. For example,

            a query of `NYC M` matches customer profiles with the `reference_id`
            value of `NYC_M_35_JOHNSON`

            and `NYC_27_MURRAY`.
          nullable: true
        group_ids:
          $ref: '#/components/schemas/FilterValue'
          description: >-
            A filter to select customers based on the
            [groups](entity:CustomerGroup) they belong to.

            Group membership is controlled by sellers and developers.


            The `group_ids` filter has the following syntax:

            ```

            "group_ids": {

            "any":  ["{group_a_id}", "{group_b_id}", ...],

            "all":  ["{group_1_id}", "{group_2_id}", ...],

            "none": ["{group_i_id}", "{group_ii_id}", ...]

            }

            ```


            You can use any combination of the `any`, `all`, and `none` fields
            in the filter.

            With `any`, the search returns customers in groups `a` or `b` or any
            other group specified in the list.

            With `all`, the search returns customers in groups `1` and `2` and
            all other groups specified in the list.

            With `none`, the search returns customers not in groups `i` or `ii`
            or any other group specified in the list.


            If any of the search conditions are not met, including when an
            invalid or non-existent group ID is provided,

            the result is an empty object (`{}`).
          nullable: true
        custom_attribute:
          $ref: '#/components/schemas/CustomerCustomAttributeFilters'
          description: >-
            A filter to select customers based on one or more custom
            attributes.  

            This filter can contain up to 10 custom attribute filters. Each
            custom attribute filter specifies filtering criteria for a target
            custom

            attribute. If multiple custom attribute filters are provided, they
            are combined as an `AND` operation.


            To be valid for a search, the custom attributes must be visible to
            the requesting application. For more information, including example
            queries,

            see [Search by custom
            attribute](https://developer.squareup.com/docs/customers-api/use-the-api/search-customers#search-by-custom-attribute).


            Square returns matching customer profiles, which do not contain
            custom attributes. To retrieve customer-related custom attributes,

            use the [Customer Custom Attributes
            API](api:CustomerCustomAttributes). For example, you can call

            [RetrieveCustomerCustomAttribute](api-endpoint:CustomerCustomAttributes-RetrieveCustomerCustomAttribute)
            using a customer ID from the result set.
          nullable: true
        segment_ids:
          $ref: '#/components/schemas/FilterValue'
          description: >2-
             A filter to select customers based on the [segments](entity:CustomerSegment) they belong to.
            Segment membership is dynamic and adjusts automatically based on
            whether customers meet the segment criteria.


            You can provide up to three segment IDs in the filter, using any
            combination of the `all`, `any`, and `none` fields.

            For the following example, the results include customers who belong
            to both segment A and segment B but do not belong to segment C.


            ```

            "segment_ids": {

            "all":  ["{segment_A_id}", "{segment_B_id}"],

            "none":  ["{segment_C_id}"]

            }

            ```


            If an invalid or non-existent segment ID is provided in the filter,
            Square stops processing the request

            and returns a `400 BAD_REQUEST` error that includes the segment ID.
          nullable: true
    CustomerGroup:
      type: object
      description: >-
        Represents a group of customer profiles. 


        Customer groups can be created, be modified, and have their membership
        defined using 

        the Customers API or within the Customer Directory in the Square Seller
        Dashboard or Point of Sale.
      x-release-status: PUBLIC
      required:
        - name
      properties:
        id:
          type: string
          description: A unique Square-generated ID for the customer group.
          maxLength: 255
          readOnly: true
        name:
          type: string
          description: The name of the customer group.
        created_at:
          type: string
          description: >-
            The timestamp when the customer group was created, in RFC 3339
            format.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp when the customer group was last updated, in RFC 3339
            format.
          readOnly: true
    CustomerInclusionExclusion:
      type: string
      enum:
        - INCLUDE
        - EXCLUDE
      x-enum-elements:
        - name: INCLUDE
          description: |-
            Customers should be included in the result set when they match the
            filtering criteria.
        - name: EXCLUDE
          description: |-
            Customers should be excluded from the result set when they match
            the filtering criteria.
      description: |-
        Indicates whether customers should be included in, or excluded from,
        the result set when they match the filtering criteria.
      x-release-status: PUBLIC
    CustomerPreferences:
      type: object
      description: Represents communication preferences for the customer profile.
      x-release-status: PUBLIC
      properties:
        email_unsubscribed:
          type: boolean
          description: >-
            Indicates whether the customer has unsubscribed from marketing
            campaign emails. A value of `true` means that the customer chose to
            opt out of email marketing from the current Square seller or from
            all Square sellers. This value is read-only from the Customers API.
          nullable: true
    CustomerQuery:
      type: object
      description: >-
        Represents filtering and sorting criteria for a
        [SearchCustomers](api-endpoint:Customers-SearchCustomers) request.
      x-release-status: PUBLIC
      properties:
        filter:
          $ref: '#/components/schemas/CustomerFilter'
          description: >-
            The filtering criteria for the search query. A query can contain
            multiple filters in any combination.

            Multiple filters are combined as `AND` statements.


            __Note:__ Combining multiple filters as `OR` statements is not
            supported. Instead, send multiple single-filter

            searches and join the result sets.
          nullable: true
        sort:
          $ref: '#/components/schemas/CustomerSort'
          description: |-
            Sorting criteria for query results. The default behavior is to sort 
            customers alphabetically by `given_name` and `family_name`.
          nullable: true
    CustomerSegment:
      type: object
      description: >-
        Represents a group of customer profiles that match one or more
        predefined filter criteria. 


        Segments (also known as Smart Groups) are defined and created within the
        Customer Directory in the

        Square Seller Dashboard or Point of Sale.
      x-release-status: PUBLIC
      required:
        - name
      properties:
        id:
          type: string
          description: A unique Square-generated ID for the segment.
          maxLength: 255
          readOnly: true
        name:
          type: string
          description: The name of the segment.
          readOnly: true
        created_at:
          type: string
          description: The timestamp when the segment was created, in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: The timestamp when the segment was last updated, in RFC 3339 format.
          readOnly: true
    CustomerSort:
      type: object
      description: >-
        Represents the sorting criteria in a [search
        query](entity:CustomerQuery) that defines how to sort

        customer profiles returned in
        [SearchCustomers](api-endpoint:Customers-SearchCustomers) results.
      x-release-status: PUBLIC
      properties:
        field:
          $ref: '#/components/schemas/CustomerSortField'
          description: >-
            Indicates the fields to use as the sort key, which is either the
            default set of fields or `created_at`.


            The default value is `DEFAULT`.

            See [CustomerSortField](#type-customersortfield) for possible values
          nullable: true
        order:
          $ref: '#/components/schemas/SortOrder'
          description: >-
            Indicates the order in which results should be sorted based on the

            sort field value. Strings use standard alphabetic comparison

            to determine order. Strings representing numbers are sorted as
            strings.


            The default value is `ASC`.

            See [SortOrder](#type-sortorder) for possible values
          nullable: true
    CustomerSortField:
      type: string
      enum:
        - DEFAULT
        - CREATED_AT
      x-enum-elements:
        - name: DEFAULT
          description: >-
            Use the default sort key. By default, customers are sorted

            alphanumerically by concatenating their `given_name` and
            `family_name`. If

            neither name field is set, string comparison is performed using one
            of the

            remaining fields in the following order: `company_name`, `email`,

            `phone_number`.
        - name: CREATED_AT
          description: >-
            Use the creation date attribute (`created_at`) of customer profiles
            as the sort key.
      description: >-
        Specifies customer attributes as the sort key to customer profiles
        returned from a search.
      x-release-status: PUBLIC
    CustomerTaxIds:
      type: object
      description: >-
        Represents the tax ID associated with a [customer
        profile](entity:Customer). The corresponding `tax_ids` field is
        available only for customers of sellers in EU countries or the United
        Kingdom. 

        For more information, see [Customer tax
        IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids).
      x-release-status: PUBLIC
      properties:
        eu_vat:
          type: string
          description: >-
            The EU VAT identification number for the customer. For example,
            `IE3426675K`. The ID can contain alphanumeric characters only.
          maxLength: 20
          nullable: true
    CustomerTextFilter:
      type: object
      description: >-
        A filter to select customers based on exact or fuzzy matching of

        customer attributes against a specified query. Depending on the customer
        attributes, 

        the filter can be case-sensitive. This filter can be exact or fuzzy, but
        it cannot be both.
      x-release-status: PUBLIC
      properties:
        exact:
          type: string
          description: >-
            Use the exact filter to select customers whose attributes match
            exactly the specified query.
          nullable: true
        fuzzy:
          type: string
          description: >-
            Use the fuzzy filter to select customers whose attributes match the
            specified query 

            in a fuzzy manner. When the fuzzy option is used, search queries are
            tokenized, and then 

            each query token must be matched somewhere in the searched
            attribute. For single token queries, 

            this is effectively the same behavior as a partial match operation.
          nullable: true
    DataCollectionOptions:
      type: object
      x-release-status: BETA
      required:
        - title
        - body
        - input_type
      properties:
        title:
          type: string
          description: >-
            The title text to display in the data collection flow on the
            Terminal.
          minLength: 1
          maxLength: 250
        body:
          type: string
          description: >-
            The body text to display under the title in the data collection
            screen flow on the

            Terminal.
          minLength: 1
          maxLength: 10000
        input_type:
          $ref: '#/components/schemas/DataCollectionOptionsInputType'
          description: |-
            Represents the type of the input text.
            See [InputType](#type-inputtype) for possible values
        collected_data:
          $ref: '#/components/schemas/CollectedData'
          description: The buyers input text from the data collection screen.
          readOnly: true
    DataCollectionOptionsInputType:
      type: string
      enum:
        - EMAIL
        - PHONE_NUMBER
      x-enum-elements:
        - name: EMAIL
          description: >-
            This value is used to represent an input text that contains a email
            validation on the

            client.
        - name: PHONE_NUMBER
          description: >-
            This value is used to represent an input text that contains a phone
            number validation on

            the client.
      description: Describes the input type of the data.
      x-release-status: BETA
    DateRange:
      type: object
      description: |-
        A range defined by two dates. Used for filtering a query for Connect v2
        objects that have date properties.
      x-release-status: PUBLIC
      properties:
        start_date:
          type: string
          description: >-
            A string in `YYYY-MM-DD` format, such as `2017-10-31`, per the ISO
            8601

            extended format for calendar dates.

            The beginning of a date range (inclusive).
          nullable: true
        end_date:
          type: string
          description: >-
            A string in `YYYY-MM-DD` format, such as `2017-10-31`, per the ISO
            8601

            extended format for calendar dates.

            The end of a date range (inclusive).
          nullable: true
    DayOfWeek:
      type: string
      enum:
        - SUN
        - MON
        - TUE
        - WED
        - THU
        - FRI
        - SAT
      x-enum-elements:
        - name: SUN
          description: Sunday
        - name: MON
          description: Monday
        - name: TUE
          description: Tuesday
        - name: WED
          description: Wednesday
        - name: THU
          description: Thursday
        - name: FRI
          description: Friday
        - name: SAT
          description: Saturday
      description: Indicates the specific day  of the week.
      x-release-status: PUBLIC
    DeleteBookingCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents a
        [DeleteBookingCustomAttributeDefinition](api-endpoint:BookingCustomAttributes-DeleteBookingCustomAttributeDefinition)
        request.
      x-release-status: PUBLIC
      properties: {}
    DeleteBookingCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a
        [DeleteBookingCustomAttributeDefinition](api-endpoint:BookingCustomAttributes-DeleteBookingCustomAttributeDefinition)
        response

        containing error messages when errors occurred during the request. The
        successful response does not contain any payload.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        errors: []
    DeleteBookingCustomAttributeRequest:
      type: object
      description: >-
        Represents a
        [DeleteBookingCustomAttribute](api-endpoint:BookingCustomAttributes-DeleteBookingCustomAttribute)
        request.
      x-release-status: PUBLIC
      properties: {}
    DeleteBookingCustomAttributeResponse:
      type: object
      description: >-
        Represents a
        [DeleteBookingCustomAttribute](api-endpoint:BookingCustomAttributes-DeleteBookingCustomAttribute)
        response.

        Either an empty object `{}` (for a successful deletion) or `errors` is
        present in the response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        errors: []
    DeleteBreakTypeRequest:
      type: object
      description: A request to delete a `BreakType`.
      x-release-status: PUBLIC
      properties: {}
    DeleteBreakTypeResponse:
      type: object
      description: >-
        The response to a request to delete a `BreakType`. The response might
        contain a set 

        of `Error` objects if the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    DeleteCatalogObjectRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/DeleteCatalogObject/DeleteCatalogObjectRequest.csharp
        java: >-
          /sdk_samples/Catalog/DeleteCatalogObject/DeleteCatalogObjectRequest.java
        javascript: >-
          /sdk_samples/Catalog/DeleteCatalogObject/DeleteCatalogObjectRequest.javascript
        php: >-
          /sdk_samples/Catalog/DeleteCatalogObject/DeleteCatalogObjectRequest.php
        python: >-
          /sdk_samples/Catalog/DeleteCatalogObject/DeleteCatalogObjectRequest.python
        ruby: >-
          /sdk_samples/Catalog/DeleteCatalogObject/DeleteCatalogObjectRequest.ruby
    DeleteCatalogObjectResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        deleted_object_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of all catalog objects deleted by this request.

            Multiple IDs may be returned when associated objects are also
            deleted, for example

            a catalog item variation will be deleted (and its ID included in
            this field)

            when its parent catalog item is deleted.
        deleted_at:
          type: string
          description: >-
            The database
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            of this deletion in RFC 3339 format, e.g.,
            `2016-09-04T23:59:33.123Z`.
      example:
        deleted_at: '2016-11-16T22:25:24.878Z'
        deleted_object_ids:
          - 7SB3ZQYJ5GDMVFL7JK46JCHT
          - KQLFFHA6K6J3YQAQAWDQAL57
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/DeleteCatalogObject/DeleteCatalogObjectResponse.csharp
        java: >-
          /sdk_samples/Catalog/DeleteCatalogObject/DeleteCatalogObjectResponse.java
        javascript: >-
          /sdk_samples/Catalog/DeleteCatalogObject/DeleteCatalogObjectResponse.javascript
        php: >-
          /sdk_samples/Catalog/DeleteCatalogObject/DeleteCatalogObjectResponse.php
        python: >-
          /sdk_samples/Catalog/DeleteCatalogObject/DeleteCatalogObjectResponse.python
        ruby: >-
          /sdk_samples/Catalog/DeleteCatalogObject/DeleteCatalogObjectResponse.ruby
    DeleteCustomerCardRequest:
      type: object
      description: |-
        Defines the fields that are included in requests to the
        `DeleteCustomerCard` endpoint.
      x-release-status: DEPRECATED
      properties: {}
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/DeleteCustomerCard/DeleteCustomerCardRequest.csharp
        java: /sdk_samples/DeleteCustomerCard/DeleteCustomerCardRequest.java
        javascript: /sdk_samples/DeleteCustomerCard/DeleteCustomerCardRequest.javascript
        php: /sdk_samples/DeleteCustomerCard/DeleteCustomerCardRequest.php
        python: /sdk_samples/DeleteCustomerCard/DeleteCustomerCardRequest.python
        ruby: /sdk_samples/DeleteCustomerCard/DeleteCustomerCardRequest.ruby
    DeleteCustomerCardResponse:
      type: object
      description: |-
        Defines the fields that are included in the response body of
        a request to the `DeleteCustomerCard` endpoint.
      x-release-status: DEPRECATED
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/DeleteCustomerCard/DeleteCustomerCardResponse.csharp
        java: /sdk_samples/DeleteCustomerCard/DeleteCustomerCardResponse.java
        javascript: /sdk_samples/DeleteCustomerCard/DeleteCustomerCardResponse.javascript
        php: /sdk_samples/DeleteCustomerCard/DeleteCustomerCardResponse.php
        python: /sdk_samples/DeleteCustomerCard/DeleteCustomerCardResponse.python
        ruby: /sdk_samples/DeleteCustomerCard/DeleteCustomerCardResponse.ruby
    DeleteCustomerCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents a
        [DeleteCustomerCustomAttributeDefinition](api-endpoint:CustomerCustomAttributes-DeleteCustomerCustomAttributeDefinition)
        request.
      x-release-status: PUBLIC
      x-params-example: '?key=favoritemovie'
      properties: {}
    DeleteCustomerCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a response from a delete request containing error messages if
        there are any.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    DeleteCustomerCustomAttributeRequest:
      type: object
      description: >-
        Represents a
        [DeleteCustomerCustomAttribute](api-endpoint:CustomerCustomAttributes-DeleteCustomerCustomAttribute)
        request.
      x-release-status: PUBLIC
      x-params-example: '?customer_id=Z57QXKM2FGXEQDV42W8RBZY7BR&key=favoritemovie'
      properties: {}
    DeleteCustomerCustomAttributeResponse:
      type: object
      description: >-
        Represents a
        [DeleteCustomerCustomAttribute](api-endpoint:CustomerCustomAttributes-DeleteCustomerCustomAttribute)
        response.

        Either an empty object `{}` (for a successful deletion) or `errors` is
        present in the response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    DeleteCustomerGroupRequest:
      type: object
      description: >-
        Defines the fields that can be included in a request to the

        [DeleteCustomerGroup](api-endpoint:CustomerGroups-DeleteCustomerGroup)
        endpoint.
      x-release-status: PUBLIC
      properties: {}
      example: {}
    DeleteCustomerGroupResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [DeleteCustomerGroup](api-endpoint:CustomerGroups-DeleteCustomerGroup)
        endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    DeleteCustomerRequest:
      type: object
      description: >-
        Defines the fields that are included in a request to the
        `DeleteCustomer`

        endpoint.
      x-release-status: PUBLIC
      x-params-example: '?version=11'
      properties:
        version:
          type: integer
          description: >-
            The current version of the customer profile.


            As a best practice, you should include this parameter to enable
            [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)
            control.  For more information, see [Delete a customer
            profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#delete-customer-profile).
          format: int64
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/DeleteCustomer/DeleteCustomerRequest.csharp
        java: /sdk_samples/DeleteCustomer/DeleteCustomerRequest.java
        javascript: /sdk_samples/DeleteCustomer/DeleteCustomerRequest.javascript
        php: /sdk_samples/DeleteCustomer/DeleteCustomerRequest.php
        python: /sdk_samples/DeleteCustomer/DeleteCustomerRequest.python
        ruby: /sdk_samples/DeleteCustomer/DeleteCustomerRequest.ruby
    DeleteCustomerResponse:
      type: object
      description: |-
        Defines the fields that are included in the response body of
        a request to the `DeleteCustomer` endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/DeleteCustomer/DeleteCustomerResponse.csharp
        java: /sdk_samples/DeleteCustomer/DeleteCustomerResponse.java
        javascript: /sdk_samples/DeleteCustomer/DeleteCustomerResponse.javascript
        php: /sdk_samples/DeleteCustomer/DeleteCustomerResponse.php
        python: /sdk_samples/DeleteCustomer/DeleteCustomerResponse.python
        ruby: /sdk_samples/DeleteCustomer/DeleteCustomerResponse.ruby
    DeleteDisputeEvidenceRequest:
      type: object
      description: Defines the parameters for a `DeleteDisputeEvidence` request.
      x-release-status: PUBLIC
      x-params-example: '?dispute_id=bVTprrwk0gygTLZ96VX1oB&evidence_id=CpfnkwGselCwS8QFvxN6'
      properties: {}
      example: {}
    DeleteDisputeEvidenceResponse:
      type: object
      description: Defines the fields in a `DeleteDisputeEvidence` response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example: {}
    DeleteInvoiceAttachmentRequest:
      type: object
      description: >-
        Represents a
        [DeleteInvoiceAttachment](api-endpoint:Invoices-DeleteInvoiceAttachment)
        request.
      x-release-status: PUBLIC
      properties: {}
    DeleteInvoiceAttachmentResponse:
      type: object
      description: >-
        Represents a
        [DeleteInvoiceAttachment](api-endpoint:Invoices-DeleteInvoiceAttachment)
        response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example: {}
    DeleteInvoiceRequest:
      type: object
      description: Describes a `DeleteInvoice` request.
      x-release-status: PUBLIC
      properties:
        version:
          type: integer
          description: >-
            The version of the [invoice](entity:Invoice) to delete.

            If you do not know the version, you can call
            [GetInvoice](api-endpoint:Invoices-GetInvoice) or 

            [ListInvoices](api-endpoint:Invoices-ListInvoices).
    DeleteInvoiceResponse:
      type: object
      description: Describes a `DeleteInvoice` response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example: {}
    DeleteLocationCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents a
        [DeleteLocationCustomAttributeDefinition](api-endpoint:LocationCustomAttributes-DeleteLocationCustomAttributeDefinition)
        request.
      x-release-status: BETA
      x-params-example: '?key=bestseller'
      properties: {}
    DeleteLocationCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a response from a delete request containing error messages if
        there are any.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    DeleteLocationCustomAttributeRequest:
      type: object
      description: >-
        Represents a
        [DeleteLocationCustomAttribute](api-endpoint:LocationCustomAttributes-DeleteLocationCustomAttribute)
        request.
      x-release-status: BETA
      x-params-example: '?location_id=L0TBCBTB7P8RQ&key=bestseller'
      properties: {}
    DeleteLocationCustomAttributeResponse:
      type: object
      description: >-
        Represents a
        [DeleteLocationCustomAttribute](api-endpoint:LocationCustomAttributes-DeleteLocationCustomAttribute)
        response.

        Either an empty object `{}` (for a successful deletion) or `errors` is
        present in the response.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    DeleteLoyaltyRewardRequest:
      type: object
      description: A request to delete a loyalty reward.
      x-release-status: PUBLIC
      x-params-example: '?reward_id=9f18ac21-233a-31c3-be77-b45840f5a810'
      properties: {}
    DeleteLoyaltyRewardResponse:
      type: object
      description: A response returned by the API call.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    DeleteMerchantCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents a
        [DeleteMerchantCustomAttributeDefinition](api-endpoint:MerchantCustomAttributes-DeleteMerchantCustomAttributeDefinition)
        request.
      x-release-status: BETA
      x-params-example: '?key=alternative_seller_name'
      properties: {}
    DeleteMerchantCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a response from a delete request containing error messages if
        there are any.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    DeleteMerchantCustomAttributeRequest:
      type: object
      description: >-
        Represents a
        [DeleteMerchantCustomAttribute](api-endpoint:MerchantCustomAttributes-DeleteMerchantCustomAttribute)
        request.
      x-release-status: BETA
      x-params-example: '?merchant_id=DM7VKY8Q63GNP&key=alternative_seller_name'
      properties: {}
    DeleteMerchantCustomAttributeResponse:
      type: object
      description: >-
        Represents a
        [DeleteMerchantCustomAttribute](api-endpoint:MerchantCustomAttributes-DeleteMerchantCustomAttribute)
        response.

        Either an empty object `{}` (for a successful deletion) or `errors` is
        present in the response.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    DeleteOrderCustomAttributeDefinitionRequest:
      type: object
      description: Represents a delete request for an order custom attribute definition.
      x-release-status: BETA
      x-params-example: '?key=table-number'
      properties: {}
    DeleteOrderCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a response from deleting an order custom attribute
        definition.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    DeleteOrderCustomAttributeRequest:
      type: object
      description: Represents a delete request for an order custom attribute.
      x-release-status: BETA
      x-params-example: '?order_id=7BbXGEIWNldxAzrtGf9GPVZTwZ4F&key=seat-number'
      properties: {}
    DeleteOrderCustomAttributeResponse:
      type: object
      description: Represents a response from deleting an order custom attribute.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    DeletePaymentLinkRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
    DeletePaymentLinkResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        id:
          type: string
          description: The ID of the link that is deleted.
        cancelled_order_id:
          type: string
          description: >-
            The ID of the order that is canceled. When a payment link is
            deleted, Square updates the

            the `state` (of the order that the checkout link created) to
            CANCELED.
      example:
        cancelled_order_id: asx8LgZ6MRzD0fObfkJ6obBmSh4F
        id: MQASNYL6QB6DFCJ3
    DeleteShiftRequest:
      type: object
      description: A request to delete a `Shift`.
      x-release-status: PUBLIC
      properties: {}
    DeleteShiftResponse:
      type: object
      description: >-
        The response to a request to delete a `Shift`. The response might
        contain a set of 

        `Error` objects if the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    DeleteSnippetRequest:
      type: object
      description: Represents a `DeleteSnippet` request.
      x-release-status: PUBLIC
      properties: {}
    DeleteSnippetResponse:
      type: object
      description: Represents a `DeleteSnippet` response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    DeleteSubscriptionActionRequest:
      type: object
      description: >-
        Defines input parameters in a call to the 

        [DeleteSubscriptionAction](api-endpoint:Subscriptions-DeleteSubscriptionAction)

        endpoint.
      x-release-status: BETA
      properties: {}
    DeleteSubscriptionActionResponse:
      type: object
      description: >-
        Defines output parameters in a response of the
        [DeleteSubscriptionAction](api-endpoint:Subscriptions-DeleteSubscriptionAction)

        endpoint.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered during the request.
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: The subscription that has the specified action deleted.
      example:
        subscription:
          card_id: ccof:IkWfpLj4tNHMyFii3GB
          charged_through_date: '2023-11-20'
          created_at: '2022-07-27T21:53:10Z'
          customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4
          id: 8151fc89-da15-4eb9-a685-1a70883cebfc
          invoice_ids:
            - inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
            - inv:0-ChrcX_i3sNmfsHTGKhI4Wg2mceA
          location_id: S8GWD5R9QB376
          paid_until_date: '2024-08-01'
          plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
          price_override_money:
            amount: 25000
            currency: USD
          source:
            name: My Application
          start_date: '2022-07-27'
          status: ACTIVE
          timezone: America/Los_Angeles
    DeleteWebhookSubscriptionRequest:
      type: object
      description: Deletes a [Subscription](entity:WebhookSubscription).
      x-release-status: PUBLIC
      properties: {}
    DeleteWebhookSubscriptionResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [DeleteWebhookSubscription](api-endpoint:WebhookSubscriptions-DeleteWebhookSubscription)
        endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
      example: {}
    DeprecatedCreateDisputeEvidenceFileRequest:
      type: object
      description: >-
        Defines the parameters for a `DeprecatedCreateDisputeEvidenceFile`
        request.
      x-release-status: PUBLIC
      required:
        - idempotency_key
      properties:
        idempotency_key:
          type: string
          description: >-
            The Unique ID. For more information, see
            [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).
          minLength: 1
          maxLength: 45
        evidence_type:
          $ref: '#/components/schemas/DisputeEvidenceType'
          description: >-
            The type of evidence you are uploading.

            See [DisputeEvidenceType](#type-disputeevidencetype) for possible
            values
          nullable: true
        content_type:
          type: string
          description: >-
            The MIME type of the uploaded file.

            The type can be image/heic, image/heif, image/jpeg, application/pdf,
            image/png, or image/tiff.
          minLength: 1
          maxLength: 40
          nullable: true
    DeprecatedCreateDisputeEvidenceFileResponse:
      type: object
      description: Defines the fields in a `DeprecatedCreateDisputeEvidenceFile` response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        evidence:
          $ref: '#/components/schemas/DisputeEvidence'
          description: The metadata of the newly uploaded dispute evidence.
      example:
        evidence:
          dispute_id: bVTprrwk0gygTLZ96VX1oB
          evidence_file:
            filename: evidence.tiff
            filetype: image/tiff
          evidence_id: TOomLInj6iWmP3N8qfCXrB
          evidence_type: GENERIC_EVIDENCE
          uploaded_at: '2018-10-18T16:01:10.000Z'
    DeprecatedCreateDisputeEvidenceTextRequest:
      type: object
      description: >-
        Defines the parameters for a `DeprecatedCreateDisputeEvidenceText`
        request.
      x-release-status: PUBLIC
      required:
        - idempotency_key
        - evidence_text
      properties:
        idempotency_key:
          type: string
          description: >-
            The Unique ID. For more information, see
            [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).
          minLength: 1
          maxLength: 45
        evidence_type:
          $ref: '#/components/schemas/DisputeEvidenceType'
          description: >-
            The type of evidence you are uploading.

            See [DisputeEvidenceType](#type-disputeevidencetype) for possible
            values
          nullable: true
        evidence_text:
          type: string
          description: The evidence string.
          minLength: 1
          maxLength: 500
      example:
        evidence_text: 1Z8888888888888888
        evidence_type: TRACKING_NUMBER
        idempotency_key: ed3ee3933d946f1514d505d173c82648
    DeprecatedCreateDisputeEvidenceTextResponse:
      type: object
      description: Defines the fields in a `DeprecatedCreateDisputeEvidenceText` response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        evidence:
          $ref: '#/components/schemas/DisputeEvidence'
          description: The newly uploaded dispute evidence metadata.
      example:
        evidence:
          dispute_id: bVTprrwk0gygTLZ96VX1oB
          evidence_text: The customer purchased the item twice, on April 11 and April 28.
          evidence_type: REBUTTAL_EXPLANATION
          id: TOomLInj6iWmP3N8qfCXrB
          uploaded_at: '2022-05-18T16:01:10.000Z'
    Destination:
      type: object
      description: Information about the destination against which the payout was made.
      x-release-status: PUBLIC
      properties:
        type:
          $ref: '#/components/schemas/DestinationType'
          description: |-
            Type of the destination such as a bank account or debit card.
            See [DestinationType](#type-destinationtype) for possible values
          nullable: true
        id:
          type: string
          description: >-
            Square issued unique ID (also known as the instrument ID) associated
            with this destination.
    DestinationDetails:
      type: object
      description: Details about a refund's destination.
      x-release-status: PUBLIC
      properties:
        card_details:
          $ref: '#/components/schemas/DestinationDetailsCardRefundDetails'
          description: >-
            Details about a card refund. Only populated if the destination_type
            is `CARD`.
          nullable: true
        cash_details:
          $ref: '#/components/schemas/DestinationDetailsCashRefundDetails'
          description: >-
            Details about a cash refund. Only populated if the destination_type
            is `CASH`.
          nullable: true
        external_details:
          $ref: '#/components/schemas/DestinationDetailsExternalRefundDetails'
          description: >-
            Details about an external refund. Only populated if the
            destination_type is `EXTERNAL`.
          nullable: true
    DestinationDetailsCardRefundDetails:
      type: object
      x-release-status: PUBLIC
      properties:
        card:
          $ref: '#/components/schemas/Card'
          description: The card's non-confidential details.
          nullable: true
        entry_method:
          type: string
          description: >-
            The method used to enter the card's details for the refund. The
            method can be

            `KEYED`, `SWIPED`, `EMV`, `ON_FILE`, or `CONTACTLESS`.
          maxLength: 50
          nullable: true
        auth_result_code:
          type: string
          description: >-
            The authorization code provided by the issuer when a refund is
            approved.
          maxLength: 10
          nullable: true
    DestinationDetailsCashRefundDetails:
      type: object
      description: >-
        Stores details about a cash refund. Contains only non-confidential
        information.
      x-release-status: PUBLIC
      required:
        - seller_supplied_money
      properties:
        seller_supplied_money:
          $ref: '#/components/schemas/Money'
          description: The amount and currency of the money supplied by the seller.
        change_back_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The amount of change due back to the seller.
            This read-only field is calculated
            from the `amount_money` and `seller_supplied_money` fields.
          nullable: true
    DestinationDetailsExternalRefundDetails:
      type: object
      description: >-
        Stores details about an external refund. Contains only non-confidential
        information.
      x-release-status: PUBLIC
      required:
        - type
        - source
      properties:
        type:
          type: string
          description: >-
            The type of external refund the seller paid to the buyer. It can be
            one of the

            following:

            - CHECK - Refunded using a physical check.

            - BANK_TRANSFER - Refunded using external bank transfer.

            - OTHER\_GIFT\_CARD - Refunded using a non-Square gift card.

            - CRYPTO - Refunded using a crypto currency.

            - SQUARE_CASH - Refunded using Square Cash App.

            - SOCIAL - Refunded using peer-to-peer payment applications.

            - EXTERNAL - A third-party application gathered this refund outside
            of Square.

            - EMONEY - Refunded using an E-money provider.

            - CARD - A credit or debit card that Square does not support.

            - STORED_BALANCE - Use for house accounts, store credit, and so
            forth.

            - FOOD_VOUCHER - Restaurant voucher provided by employers to
            employees to pay for meals

            - OTHER - A type not listed here.
          maxLength: 50
        source:
          type: string
          description: |-
            A description of the external refund source. For example,
            "Food Delivery Service".
          maxLength: 255
        source_id:
          type: string
          description: An ID to associate the refund to its originating source.
          maxLength: 255
          nullable: true
    DestinationType:
      type: string
      enum:
        - BANK_ACCOUNT
        - CARD
        - SQUARE_BALANCE
        - SQUARE_STORED_BALANCE
      x-enum-elements:
        - name: BANK_ACCOUNT
          description: An external bank account outside of Square.
        - name: CARD
          description: An external card outside of Square used for the transfer.
        - name: SQUARE_BALANCE
          description: ''
        - name: SQUARE_STORED_BALANCE
          description: Square Checking or Savings account (US), Square Card (CA)
      description: List of possible destinations against which a payout can be made.
      x-release-status: PUBLIC
    Device:
      type: object
      x-release-status: BETA
      required:
        - attributes
      properties:
        id:
          type: string
          description: >-
            A synthetic identifier for the device. The identifier includes a
            standardized prefix and

            is otherwise an opaque id generated from key device fields.
          readOnly: true
        attributes:
          $ref: '#/components/schemas/DeviceAttributes'
          description: A collection of DeviceAttributes representing the device.
        components:
          type: array
          items:
            $ref: '#/components/schemas/Component'
          description: A list of components applicable to the device.
          nullable: true
        status:
          $ref: '#/components/schemas/DeviceStatus'
          description: The current status of the device.
          readOnly: true
    DeviceAttributes:
      type: object
      x-release-status: BETA
      required:
        - type
        - manufacturer
      properties:
        type:
          $ref: '#/components/schemas/DeviceAttributesDeviceType'
          description: |-
            The device type.
            See [DeviceType](#type-devicetype) for possible values
        manufacturer:
          type: string
          description: The maker of the device.
        model:
          type: string
          description: The specific model of the device.
          nullable: true
        name:
          type: string
          description: A seller-specified name for the device.
          nullable: true
        manufacturers_id:
          type: string
          description: >-
            The manufacturer-supplied identifier for the device (where
            available). In many cases,

            this identifier will be a serial number.
          nullable: true
        updated_at:
          type: string
          description: >-
            The RFC 3339-formatted value of the most recent update to the device
            information.

            (Could represent any field update on the device.)
        version:
          type: string
          description: The current version of software installed on the device.
        merchant_token:
          type: string
          description: The merchant_token identifying the merchant controlling the device.
          nullable: true
    DeviceAttributesDeviceType:
      type: string
      enum:
        - TERMINAL
      x-enum-elements:
        - name: TERMINAL
          description: ''
      description: An enum identifier of the device type.
      x-release-status: BETA
    DeviceCheckoutOptions:
      type: object
      x-release-status: PUBLIC
      required:
        - device_id
      properties:
        device_id:
          type: string
          description: >-
            The unique ID of the device intended for this `TerminalCheckout`.

            A list of `DeviceCode` objects can be retrieved from the
            /v2/devices/codes endpoint.

            Match a `DeviceCode.device_id` value with `device_id` to get the
            associated device code.
        skip_receipt_screen:
          type: boolean
          description: Instructs the device to skip the receipt screen. Defaults to false.
          nullable: true
        collect_signature:
          type: boolean
          description: >-
            Indicates that signature collection is desired during checkout.
            Defaults to false.
          nullable: true
        tip_settings:
          $ref: '#/components/schemas/TipSettings'
          description: Tip-specific settings.
          nullable: true
        show_itemized_cart:
          type: boolean
          description: >-
            Show the itemization screen prior to taking a payment. This field is
            only meaningful when the

            checkout includes an order ID. Defaults to true.
          x-release-status: BETA
          nullable: true
    DeviceCode:
      type: object
      x-release-status: PUBLIC
      required:
        - product_type
      properties:
        id:
          type: string
          description: The unique id for this device code.
          readOnly: true
        name:
          type: string
          description: An optional user-defined name for the device code.
          maxLength: 128
          nullable: true
        code:
          type: string
          description: The unique code that can be used to login.
          readOnly: true
        device_id:
          type: string
          description: >-
            The unique id of the device that used this code. Populated when the
            device is paired up.
          readOnly: true
        product_type:
          $ref: '#/components/schemas/ProductType'
          description: The targeting product type of the device code.
        location_id:
          type: string
          description: The location assigned to this code.
          maxLength: 50
          nullable: true
        status:
          $ref: '#/components/schemas/DeviceCodeStatus'
          description: |-
            The pairing status of the device code.
            See [DeviceCodeStatus](#type-devicecodestatus) for possible values
          readOnly: true
        pair_by:
          type: string
          description: >-
            When this DeviceCode will expire and no longer login. Timestamp in
            RFC 3339 format.
          readOnly: true
        created_at:
          type: string
          description: When this DeviceCode was created. Timestamp in RFC 3339 format.
          readOnly: true
        status_changed_at:
          type: string
          description: >-
            When this DeviceCode's status was last changed. Timestamp in RFC
            3339 format.
          readOnly: true
        paired_at:
          type: string
          description: When this DeviceCode was paired. Timestamp in RFC 3339 format.
          readOnly: true
    DeviceCodeStatus:
      type: string
      enum:
        - UNKNOWN
        - UNPAIRED
        - PAIRED
        - EXPIRED
      x-enum-elements:
        - name: UNKNOWN
          description: The status cannot be determined or does not exist.
        - name: UNPAIRED
          description: The device code is just created and unpaired.
        - name: PAIRED
          description: The device code has been signed in and paired to a device.
        - name: EXPIRED
          description: The device code was unpaired and expired before it was paired.
      description: DeviceCode.Status enum.
      x-release-status: PUBLIC
    DeviceComponentDetails:
      type: object
      x-release-status: BETA
      properties: {}
    DeviceComponentDetailsApplicationDetails:
      type: object
      x-release-status: BETA
      properties:
        application_type:
          $ref: '#/components/schemas/ApplicationType'
          description: |-
            The type of application.
            See [ApplicationType](#type-applicationtype) for possible values
          nullable: true
        version:
          type: string
          description: The version of the application.
        session_location:
          type: string
          description: The location_id of the session for the application.
          nullable: true
        device_code_id:
          type: string
          description: The id of the device code that was used to log in to the device.
          nullable: true
    DeviceComponentDetailsBatteryDetails:
      type: object
      x-release-status: BETA
      properties:
        visible_percent:
          type: integer
          description: The battery charge percentage as displayed on the device.
          nullable: true
        external_power:
          $ref: '#/components/schemas/DeviceComponentDetailsExternalPower'
          description: |-
            The status of external_power.
            See [ExternalPower](#type-externalpower) for possible values
          nullable: true
    DeviceComponentDetailsCardReaderDetails:
      type: object
      x-release-status: BETA
      properties:
        version:
          type: string
          description: The version of the card reader.
    DeviceComponentDetailsEthernetDetails:
      type: object
      x-release-status: BETA
      properties:
        active:
          type: boolean
          description: >-
            A boolean to represent whether the Ethernet interface is currently
            active.
          nullable: true
        ip_address_v4:
          type: string
          description: The string representation of the devices IPv4 address.
          nullable: true
    DeviceComponentDetailsExternalPower:
      type: string
      enum:
        - AVAILABLE_CHARGING
        - AVAILABLE_NOT_IN_USE
        - UNAVAILABLE
        - AVAILABLE_INSUFFICIENT
      x-enum-elements:
        - name: AVAILABLE_CHARGING
          description: Plugged in and charging.
        - name: AVAILABLE_NOT_IN_USE
          description: Fully charged.
        - name: UNAVAILABLE
          description: On battery power.
        - name: AVAILABLE_INSUFFICIENT
          description: Not providing enough power for the device.
      description: An enum for ExternalPower.
      x-release-status: BETA
    DeviceComponentDetailsMeasurement:
      type: object
      description: A value qualified by unit of measure.
      x-release-status: BETA
      properties:
        value:
          type: integer
          nullable: true
    DeviceComponentDetailsNetworkInterfaceDetails:
      type: object
      x-release-status: BETA
      properties:
        ip_address_v4:
          type: string
          description: The string representation of the devices IPv4 address.
          nullable: true
    DeviceComponentDetailsWiFiDetails:
      type: object
      x-release-status: BETA
      properties:
        active:
          type: boolean
          description: >-
            A boolean to represent whether the WiFI interface is currently
            active.
          nullable: true
        ssid:
          type: string
          description: The name of the connected WIFI network.
          nullable: true
        ip_address_v4:
          type: string
          description: The string representation of the devices IPv4 address.
          nullable: true
        secure_connection:
          type: string
          description: >-
            The security protocol for a secure connection (e.g. WPA2). None
            provided if the connection

            is unsecured.
          nullable: true
        signal_strength:
          $ref: '#/components/schemas/DeviceComponentDetailsMeasurement'
          description: A representation of signal strength of the WIFI network connection.
          nullable: true
    DeviceDetails:
      type: object
      description: Details about the device that took the payment.
      x-release-status: PUBLIC
      properties:
        device_id:
          type: string
          description: The Square-issued ID of the device.
          maxLength: 255
          nullable: true
        device_installation_id:
          type: string
          description: The Square-issued installation ID for the device.
          maxLength: 255
          nullable: true
        device_name:
          type: string
          description: The name of the device set by the seller.
          maxLength: 255
          nullable: true
    DeviceMetadata:
      type: object
      x-release-status: BETA
      properties:
        battery_percentage:
          type: string
          description: The Terminals remaining battery percentage, between 1-100.
          nullable: true
        charging_state:
          type: string
          description: |-
            The current charging state of the Terminal.
            Options: `CHARGING`, `NOT_CHARGING`
          nullable: true
        location_id:
          type: string
          description: >-
            The ID of the Square seller business location associated with the
            Terminal.
          nullable: true
        merchant_id:
          type: string
          description: >-
            The ID of the Square merchant account that is currently signed-in to
            the Terminal.
          nullable: true
        network_connection_type:
          type: string
          description: |-
            The Terminals current network connection type.
            Options: `WIFI`, `ETHERNET`
          nullable: true
        payment_region:
          type: string
          description: The country in which the Terminal is authorized to take payments.
          nullable: true
        serial_number:
          type: string
          description: >-
            The unique identifier assigned to the Terminal, which can be found
            on the lower back

            of the device.
          nullable: true
        os_version:
          type: string
          description: The current version of the Terminals operating system.
          nullable: true
        app_version:
          type: string
          description: The current version of the application running on the Terminal.
          nullable: true
        wifi_network_name:
          type: string
          description: The name of the Wi-Fi network to which the Terminal is connected.
          nullable: true
        wifi_network_strength:
          type: string
          description: |-
            The signal strength of the Wi-FI network connection.
            Options: `POOR`, `FAIR`, `GOOD`, `EXCELLENT`
          nullable: true
        ip_address:
          type: string
          description: The IP address of the Terminal.
          nullable: true
    DeviceStatus:
      type: object
      x-release-status: BETA
      properties:
        category:
          $ref: '#/components/schemas/DeviceStatusCategory'
          description: |-

            See [Category](#type-category) for possible values
          nullable: true
    DeviceStatusCategory:
      type: string
      enum:
        - AVAILABLE
        - NEEDS_ATTENTION
        - OFFLINE
      x-enum-elements:
        - name: AVAILABLE
          description: ''
        - name: NEEDS_ATTENTION
          description: ''
        - name: OFFLINE
          description: ''
      x-release-status: BETA
    DigitalWalletDetails:
      type: object
      description: >-
        Additional details about `WALLET` type payments. Contains only
        non-confidential information.
      x-release-status: PUBLIC
      properties:
        status:
          type: string
          description: >-
            The status of the `WALLET` payment. The status can be `AUTHORIZED`,
            `CAPTURED`, `VOIDED`, or

            `FAILED`.
          maxLength: 50
          nullable: true
        brand:
          type: string
          description: >-
            The brand used for the `WALLET` payment. The brand can be
            `CASH_APP`, `PAYPAY`, `ALIPAY`,

            `RAKUTEN_PAY`, `AU_PAY`, `D_BARAI`, `MERPAY`, `WECHAT_PAY` or
            `UNKNOWN`.
          maxLength: 50
          nullable: true
        cash_app_details:
          $ref: '#/components/schemas/CashAppDetails'
          description: Brand-specific details for payments with the `brand` of `CASH_APP`.
          nullable: true
    DisableCardRequest:
      type: object
      description: >-
        Disables the card, preventing any further updates or charges. Disabling

        an already disabled card is allowed but has no effect. Accessible via

        HTTP requests at POST
        https://connect.squareup.com/v2/cards/{card_id}/disable
      x-release-status: PUBLIC
      properties: {}
      example: {}
    DisableCardResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [DisableCard](api-endpoint:Cards-DisableCard) endpoint.


        Note: if there are errors processing the request, the card field will
        not be

        present.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        card:
          $ref: '#/components/schemas/Card'
          description: The retrieved card.
      example:
        card:
          billing_address:
            address_line_1: 500 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          bin: '411111'
          card_brand: VISA
          card_type: CREDIT
          cardholder_name: Amelia Earhart
          customer_id: VDKXEEKPJN48QDG3BGGFAK05P8
          enabled: false
          exp_month: 11
          exp_year: 2022
          fingerprint: >-
            ex-p-cs80EK9Flz7LsCMv-szbptQ_ssAGrhemzSTsPFgt9nzyE6t7okiLIQc-qw_quqKX4Q
          id: ccof:uIbfJXhXETSP197M3GB
          last_4: '1111'
          merchant_id: 6SSW7HV8K2ST5
          prepaid_type: NOT_PREPAID
          reference_id: user-id-1
          version: 2
    DisableEventsRequest:
      type: object
      description: Disables [Event](entity:Event)s for your application.
      x-release-status: BETA
      properties: {}
    DisableEventsResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [DisableEvents](api-endpoint:Events-DisableEvents)
        endpoint.


        Note: if there are errors processing the request, the events field will
        not be

        present.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
      example: {}
    DismissTerminalActionRequest:
      type: object
      x-release-status: BETA
      properties: {}
      example: {}
    DismissTerminalActionResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        action:
          $ref: '#/components/schemas/TerminalAction'
          description: Current state of the action to be dismissed.
      example:
        action:
          app_id: APP_ID
          await_next_action: true
          await_next_action_duration: PT5M
          confirmation_options:
            agree_button_text: Agree
            body: >-
              I agree to receive promotional emails about future events and
              activities.
            decision:
              has_agreed: true
            disagree_button_text: Decline
            title: Marketing communications
          created_at: '2021-07-28T23:22:07.476Z'
          deadline_duration: PT5M
          device_id: DEVICE_ID
          id: termapia:abcdefg1234567
          status: COMPLETED
          type: CONFIRMATION
          updated_at: '2021-07-28T23:22:29.511Z'
    DismissTerminalCheckoutRequest:
      type: object
      x-release-status: BETA
      properties: {}
      example: {}
    DismissTerminalCheckoutResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        checkout:
          $ref: '#/components/schemas/TerminalCheckout'
          description: Current state of the checkout to be dismissed.
      example:
        checkout:
          amount_money:
            amount: 2610
            currency: USD
          app_id: APP_ID
          created_at: '2023-11-29T14:59:50.682Z'
          deadline_duration: PT5M
          device_options:
            collect_signature: true
            device_id: dbb5d83a-7838-11ea-bc55-0242ac130003
            loyalty_settings:
              loyalty_screen_max_display_duration: PT60S
              show_card_linked_reward_redemption_screen: false
              show_loyalty_screen: false
              show_non_qualifying_loyalty_screen: false
            skip_receipt_screen: false
            tip_settings:
              allow_tipping: true
              custom_tip_field: false
              separate_tip_screen: true
          id: LmZEKbo3SBfqO
          location_id: LOCATION_ID
          payment_ids:
            - D7vLJqMkvSoAlX4yyFzUitOy4EPZY
          payment_options:
            autocomplete: true
          payment_type: CARD_PRESENT
          status: COMPLETED
          updated_at: '2023-11-29T15:00:18.936Z'
    DismissTerminalRefundRequest:
      type: object
      x-release-status: BETA
      properties: {}
      example: {}
    DismissTerminalRefundResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        refund:
          $ref: '#/components/schemas/TerminalRefund'
          description: Current state of the refund to be dismissed.
      example:
        refund:
          amount_money:
            amount: 111
            currency: CAD
          app_id: APP_ID
          card:
            bin: '411111'
            card_brand: VISA
            card_type: DEBIT
            exp_month: 12
            exp_year: 2024
            fingerprint: >-
              sq-1-ElNeDpZZqUBNDI7yNghyKO-o0yLXASp4qQDGIPtxnFvTTWoqdfdP6TV8gLsSxoztXA
            last_4: '1111'
            prepaid_type: NOT_PREPAID
          card_details:
            auth_result_code: RNy6Lf
            avs_status: AVS_ACCEPTED
            card:
              bin: '411111'
              card_brand: VISA
              card_type: DEBIT
              exp_month: 12
              exp_year: 2024
              fingerprint: >-
                sq-1-ElNeDpZZqUBNDI7yNghyKO-o0yLXASp3qQDGIPtxnFvTTWoqdfdP6TV9gLsSxoztXA
              last_4: '1111'
              prepaid_type: NOT_PREPAID
            card_payment_timeline:
              authorized_at: '2023-11-30T16:15:06.645Z'
              captured_at: '2023-11-30T16:15:13.272Z'
            cvv_status: CVV_ACCEPTED
            device_details:
              device_credential:
                name: Terminal API Device created on Nov 2, 2023
                token: 9BFDXEYKB7H8Y
              device_id: f72dfb8e-4d65-4e56-aade-ec3fb8d33291
              device_installation_id: 0ef67d8e-61a3-4418-a0be-c143bfe6108d
            entry_method: SWIPED
            statement_description: SQ TREATS
            status: CAPTURED
          created_at: '2023-11-30T16:16:39.299Z'
          deadline_duration: PT5M
          device_id: 47776348fd8b32b9
          id: vjkNb2HD-xq5kiWWiJ7RhwrQnkxIn2N0l1nPZY
          order_id: s8OMhQcpEp1b61YywlccSHWqUaQZY
          payment_id: xq5kiWWiJ7RhwrQnkxIn2N0l1nPZY
          reason: Returning item
          status: IN_PROGRESS
          updated_at: '2023-11-30T16:16:57.863Z'
    Dispute:
      type: object
      description: >-
        Represents a
        [dispute](https://developer.squareup.com/docs/disputes-api/overview) a
        cardholder initiated with their bank.
      x-release-status: PUBLIC
      properties:
        dispute_id:
          type: string
          description: The unique ID for this `Dispute`, generated by Square.
          minLength: 1
          maxLength: 40
          x-release-status: DEPRECATED
          nullable: true
        id:
          type: string
          description: The unique ID for this `Dispute`, generated by Square.
          minLength: 1
          maxLength: 40
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The disputed amount, which can be less than the total transaction
            amount.

            For instance, if multiple items were purchased but the cardholder
            only initiates a dispute over some of the items.
          nullable: true
        reason:
          $ref: '#/components/schemas/DisputeReason'
          description: |-
            The reason why the cardholder initiated the dispute.
            See [DisputeReason](#type-disputereason) for possible values
          nullable: true
        state:
          $ref: '#/components/schemas/DisputeState'
          description: |-
            The current state of this dispute.
            See [DisputeState](#type-disputestate) for possible values
          nullable: true
        due_at:
          type: string
          description: >-
            The deadline by which the seller must respond to the dispute, in
            [RFC 3339
            format](https://developer.squareup.com/docs/build-basics/common-data-types/working-with-dates).
          minLength: 1
          maxLength: 40
          nullable: true
        disputed_payment:
          $ref: '#/components/schemas/DisputedPayment'
          description: The payment challenged in this dispute.
          nullable: true
        evidence_ids:
          type: array
          items:
            type: string
          description: The IDs of the evidence associated with the dispute.
          x-release-status: DEPRECATED
          nullable: true
        card_brand:
          $ref: '#/components/schemas/CardBrand'
          description: |-
            The card brand used in the disputed payment.
            See [CardBrand](#type-cardbrand) for possible values
          nullable: true
        created_at:
          type: string
          description: The timestamp when the dispute was created, in RFC 3339 format.
          minLength: 1
          maxLength: 40
          readOnly: true
        updated_at:
          type: string
          description: The timestamp when the dispute was last updated, in RFC 3339 format.
          minLength: 1
          maxLength: 40
          readOnly: true
        brand_dispute_id:
          type: string
          description: >-
            The ID of the dispute in the card brand system, generated by the
            card brand.
          minLength: 1
          maxLength: 40
          nullable: true
        reported_date:
          type: string
          description: The timestamp when the dispute was reported, in RFC 3339 format.
          minLength: 1
          maxLength: 40
          x-release-status: DEPRECATED
          nullable: true
        reported_at:
          type: string
          description: The timestamp when the dispute was reported, in RFC 3339 format.
          minLength: 1
          maxLength: 40
          nullable: true
        version:
          type: integer
          description: The current version of the `Dispute`.
        location_id:
          type: string
          description: The ID of the location where the dispute originated.
          minLength: 1
          maxLength: 40
          nullable: true
    DisputeEvidence:
      type: object
      x-release-status: PUBLIC
      properties:
        evidence_id:
          type: string
          description: The Square-generated ID of the evidence.
          minLength: 1
          maxLength: 40
          x-release-status: DEPRECATED
          nullable: true
        id:
          type: string
          description: The Square-generated ID of the evidence.
          minLength: 1
          maxLength: 40
        dispute_id:
          type: string
          description: The ID of the dispute the evidence is associated with.
          minLength: 1
          maxLength: 40
          nullable: true
        evidence_file:
          $ref: '#/components/schemas/DisputeEvidenceFile'
          description: Image, PDF, TXT
          nullable: true
        evidence_text:
          type: string
          description: Raw text
          minLength: 1
          maxLength: 500
          nullable: true
        uploaded_at:
          type: string
          description: The time when the evidence was uploaded, in RFC 3339 format.
          minLength: 1
          maxLength: 40
          nullable: true
        evidence_type:
          $ref: '#/components/schemas/DisputeEvidenceType'
          description: >-
            The type of the evidence.

            See [DisputeEvidenceType](#type-disputeevidencetype) for possible
            values
          nullable: true
    DisputeEvidenceFile:
      type: object
      description: A file to be uploaded as dispute evidence.
      x-release-status: PUBLIC
      properties:
        filename:
          type: string
          description: >-
            The file name including the file extension. For example:
            "receipt.tiff".
          minLength: 1
          maxLength: 40
          nullable: true
        filetype:
          type: string
          description: >-
            Dispute evidence files must be application/pdf, image/heic,
            image/heif, image/jpeg, image/png, or image/tiff formats.
          minLength: 1
          maxLength: 40
          nullable: true
    DisputeEvidenceType:
      type: string
      enum:
        - GENERIC_EVIDENCE
        - ONLINE_OR_APP_ACCESS_LOG
        - AUTHORIZATION_DOCUMENTATION
        - CANCELLATION_OR_REFUND_DOCUMENTATION
        - CARDHOLDER_COMMUNICATION
        - CARDHOLDER_INFORMATION
        - PURCHASE_ACKNOWLEDGEMENT
        - DUPLICATE_CHARGE_DOCUMENTATION
        - PRODUCT_OR_SERVICE_DESCRIPTION
        - RECEIPT
        - SERVICE_RECEIVED_DOCUMENTATION
        - PROOF_OF_DELIVERY_DOCUMENTATION
        - RELATED_TRANSACTION_DOCUMENTATION
        - REBUTTAL_EXPLANATION
        - TRACKING_NUMBER
      x-enum-elements:
        - name: GENERIC_EVIDENCE
          description: >-
            Square assumes this evidence type if you do not provide a type when
            uploading evidence.


            Use when uploading evidence as a file or string.
        - name: ONLINE_OR_APP_ACCESS_LOG
          description: >-
            Server or activity logs that show proof of the cardholders identity
            and that the

            cardholder successfully ordered and received the goods (digitally or
            otherwise).

            Example evidence includes IP addresses, corresponding
            timestamps/dates, cardholders name and email

            address linked to a cardholder profile held by the seller, proof the
            same device and card (used

            in dispute) were previously used in prior undisputed transaction,
            and any related detailed activity.


            Use when uploading evidence as a file or string.
        - name: AUTHORIZATION_DOCUMENTATION
          description: >-
            Evidence that the cardholder did provide authorization for the
            charge.

            Example evidence includes a signed credit card authorization.


            Use when uploading evidence as a file.
        - name: CANCELLATION_OR_REFUND_DOCUMENTATION
          description: >-
            Evidence that the cardholder acknowledged your refund or
            cancellation policy.

            Example evidence includes a signature or checkbox showing the
            cardholders acknowledgement of your

            refund or cancellation policy.


            Use when uploading evidence as a file or string.
        - name: CARDHOLDER_COMMUNICATION
          description: >-
            Evidence that shows relevant communication with the cardholder.

            Example evidence includes emails or texts that show the cardholder
            received goods/services or

            demonstrate cardholder satisfaction.


            Use when uploading evidence as a file.
        - name: CARDHOLDER_INFORMATION
          description: >-
            Evidence that validates the customer's identity.

            Example evidence includes personally identifiable details such as
            name, email address, purchaser IP

            address, and a copy of the cardholder ID.


            Use when uploading evidence as a file or string.
        - name: PURCHASE_ACKNOWLEDGEMENT
          description: >-
            Evidence that shows proof of the sale/transaction.

            Example evidence includes an invoice, contract, or other item
            showing the customers acknowledgement

            of the purchase and your terms.


            Use when uploading evidence as a file or string.
        - name: DUPLICATE_CHARGE_DOCUMENTATION
          description: >-
            Evidence that shows the charges in question are valid and distinct
            from one another.

            Example evidence includes receipts, shipping labels, and invoices
            along with their distinct payment IDs.


            Use when uploading evidence as a file.
        - name: PRODUCT_OR_SERVICE_DESCRIPTION
          description: |-
            A description of the product or service sold.

            Use when uploading evidence as a file or string.
        - name: RECEIPT
          description: >-
            A receipt or message sent to the cardholder detailing the charge.

            Note: You do not need to upload the Square receipt; Square submits
            the receipt on your behalf.


            Use when uploading evidence as a file or string.
        - name: SERVICE_RECEIVED_DOCUMENTATION
          description: >-
            Evidence that the service was provided to the cardholder or the
            expected date that services will be rendered.

            Example evidence includes a signed delivery form, work order,
            expected delivery date, or other written agreements.


            Use when uploading evidence as a file or string.
        - name: PROOF_OF_DELIVERY_DOCUMENTATION
          description: >-
            Evidence that shows the product was provided to the cardholder or
            the expected date of delivery.

            Example evidence includes a signed delivery form or written
            agreement acknowledging receipt of the goods or services.


            Use when uploading evidence as a file or string.
        - name: RELATED_TRANSACTION_DOCUMENTATION
          description: >-
            Evidence that shows the cardholder previously processed transactions
            on the same card and did not dispute them.

            Note: Square automatically provides up to five distinct Square
            receipts for related transactions, when available.


            Use when uploading evidence as a file or string.
        - name: REBUTTAL_EXPLANATION
          description: >-
            An explanation of why the cardholders claim is invalid.

            Example evidence includes an explanation of why each distinct charge
            is a legitimate purchase, why the cardholders claim

            for credit owed due to their attempt to cancel, return, or refund is
            invalid per your stated policy and cardholder

            agreement, or an explanation of how the cardholder did not attempt
            to remedy the issue with you first to receive credit.


            Use when uploading evidence as a file or string.
        - name: TRACKING_NUMBER
          description: >-
            The tracking number for the order provided by the shipping carrier.
            If you have multiple numbers, they need to be

            submitted individually as separate pieces of evidence.


            Use when uploading evidence as a string.
      description: The type of the dispute evidence.
      x-release-status: PUBLIC
    DisputeReason:
      type: string
      enum:
        - AMOUNT_DIFFERS
        - CANCELLED
        - DUPLICATE
        - NO_KNOWLEDGE
        - NOT_AS_DESCRIBED
        - NOT_RECEIVED
        - PAID_BY_OTHER_MEANS
        - CUSTOMER_REQUESTS_CREDIT
        - EMV_LIABILITY_SHIFT
      x-enum-elements:
        - name: AMOUNT_DIFFERS
          description: >-
            The cardholder claims that they were charged the wrong amount for
            the purchase.

            To challenge this dispute, provide specific and concrete evidence
            that the cardholder agreed

            to the amount charged.
        - name: CANCELLED
          description: >-
            The cardholder claims that they attempted to return the goods or
            cancel the service.

            To challenge this dispute, provide specific and concrete evidence to
            prove that the cardholder

            is not due a refund and that the cardholder acknowledged your
            cancellation policy.
        - name: DUPLICATE
          description: >-
            The cardholder claims that they were charged twice for the same
            purchase.

            To challenge this dispute, provide specific and concrete evidence
            that shows both charges are

            legitimate and independent of one another.
        - name: NO_KNOWLEDGE
          description: >-
            The cardholder claims that they did not make this purchase nor
            authorized the charge.

            To challenge this dispute, provide specific and concrete evidence
            that proves that the cardholder

            identity was verified at the time of purchase and that the purchase
            was authorized.
        - name: NOT_AS_DESCRIBED
          description: >-
            The cardholder claims the product or service was provided, but the
            quality of the deliverable

            did not align with the expectations of the cardholder based on the
            description.

            To challenge this dispute, provide specific and concrete evidence
            that shows the cardholder is in

            possession of the product as described or received the service as
            described and agreed on.
        - name: NOT_RECEIVED
          description: >-
            The cardholder claims the product or service was not received by the
            cardholder within the

            stated time frame.

            To challenge this dispute, provide specific and concrete evidence to
            prove that the cardholder is

            in possession of or received the product or service sold.
        - name: PAID_BY_OTHER_MEANS
          description: >-
            The cardholder claims that they previously paid for this purchase.

            To challenge this dispute, provide specific and concrete evidence
            that shows both charges are

            legitimate and independent of one another or proof that you already
            provided a credit for the charge.
        - name: CUSTOMER_REQUESTS_CREDIT
          description: >-
            The cardholder claims that the purchase was canceled or returned,
            but they have not yet received

            the credit.

            To challenge this dispute, provide specific and concrete evidence to
            prove that the cardholder is not

            due a refund and that they acknowledged your cancellation and/or
            refund policy.
        - name: EMV_LIABILITY_SHIFT
          description: >-
            A chip-enabled card was not processed through a compliant chip-card
            reader (for example, it was swiped

            instead of dipped into a chip-card reader).

            You cannot challenge this dispute because the payment did not comply
            with EMV security requirements.

            For more information, see [What Is EMV?](https://squareup.com/emv)
      description: |-
        The list of possible reasons why a cardholder might initiate a
        dispute with their bank.
      x-release-status: PUBLIC
    DisputeState:
      type: string
      enum:
        - INQUIRY_EVIDENCE_REQUIRED
        - INQUIRY_PROCESSING
        - INQUIRY_CLOSED
        - EVIDENCE_REQUIRED
        - PROCESSING
        - WON
        - LOST
        - ACCEPTED
      x-enum-elements:
        - name: INQUIRY_EVIDENCE_REQUIRED
          description: The initial state of an inquiry with evidence required
        - name: INQUIRY_PROCESSING
          description: >-
            Inquiry evidence has been submitted and the bank is processing the
            inquiry
        - name: INQUIRY_CLOSED
          description: The inquiry is complete
        - name: EVIDENCE_REQUIRED
          description: The initial state of a dispute with evidence required
        - name: PROCESSING
          description: >-
            Dispute evidence has been submitted and the bank is processing the
            dispute
        - name: WON
          description: The bank has completed processing the dispute and the seller has won
        - name: LOST
          description: >-
            The bank has completed processing the dispute and the seller has
            lost
        - name: ACCEPTED
          description: The seller has accepted the dispute
      description: The list of possible dispute states.
      x-release-status: PUBLIC
    DisputedPayment:
      type: object
      description: The payment the cardholder disputed.
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: Square-generated unique ID of the payment being disputed.
          minLength: 1
          maxLength: 192
          nullable: true
    EcomVisibility:
      type: string
      enum:
        - UNINDEXED
        - UNAVAILABLE
        - HIDDEN
        - VISIBLE
      x-enum-elements:
        - name: UNINDEXED
          description: Item is not synced with Ecom (Weebly). This is the default state
        - name: UNAVAILABLE
          description: >-
            Item is synced but is unavailable within Ecom (Weebly) and Online
            Checkout
        - name: HIDDEN
          description: Option for seller to choose manually created Quick Amounts.
        - name: VISIBLE
          description: >-
            Item is synced but available within Ecom (Weebly) and Online
            Checkout but is hidden from Ecom Store.
      description: Determines item visibility in Ecom (Online Store) and Online Checkout.
      x-release-status: PUBLIC
    Employee:
      type: object
      description: >-
        An employee object that is used by the external API.


        DEPRECATED at version 2020-08-26. Replaced by
        [TeamMember](entity:TeamMember).
      x-release-status: DEPRECATED
      properties:
        id:
          type: string
          description: UUID for this object.
        first_name:
          type: string
          description: The employee's first name.
          nullable: true
        last_name:
          type: string
          description: The employee's last name.
          nullable: true
        email:
          type: string
          description: The employee's email address
          nullable: true
        phone_number:
          type: string
          description: The employee's phone number in E.164 format, i.e. "+12125554250"
          nullable: true
        location_ids:
          type: array
          items:
            type: string
          description: A list of location IDs where this employee has access to.
          nullable: true
        status:
          $ref: '#/components/schemas/EmployeeStatus'
          description: |-
            Specifies the status of the employees being fetched.
            See [EmployeeStatus](#type-employeestatus) for possible values
          nullable: true
        is_owner:
          type: boolean
          description: |-
            Whether this employee is the owner of the merchant. Each merchant
            has one owner employee, and that employee has full authority over
            the account.
          nullable: true
        created_at:
          type: string
          description: A read-only timestamp in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: A read-only timestamp in RFC 3339 format.
          readOnly: true
    EmployeeStatus:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
      x-enum-elements:
        - name: ACTIVE
          description: Specifies that the employee is in the Active state.
        - name: INACTIVE
          description: Specifies that the employee is in the Inactive state.
      description: >-
        The status of the Employee being retrieved.


        DEPRECATED at version 2020-08-26. Replaced by
        [TeamMemberStatus](entity:TeamMemberStatus).
      x-release-status: DEPRECATED
    EmployeeWage:
      type: object
      description: >-
        The hourly wage rate that an employee earns on a `Shift` for doing the
        job specified by the `title` property of this object. Deprecated at
        version 2020-08-26. Use [TeamMemberWage](entity:TeamMemberWage).
      x-release-status: DEPRECATED
      properties:
        id:
          type: string
          description: The UUID for this object.
        employee_id:
          type: string
          description: The `Employee` that this wage is assigned to.
          nullable: true
        title:
          type: string
          description: The job title that this wage relates to.
          nullable: true
        hourly_rate:
          $ref: '#/components/schemas/Money'
          description: |-
            Can be a custom-set hourly wage or the calculated effective hourly
            wage based on the annual wage and hours worked per week.
          nullable: true
    EnableEventsRequest:
      type: object
      description: Enables [Event](entity:Event)s for your application.
      x-release-status: BETA
      properties: {}
    EnableEventsResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [EnableEvents](api-endpoint:Events-EnableEvents)
        endpoint.


        Note: if there are errors processing the request, the events field will
        not be

        present.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
      example: {}
    Error:
      type: object
      description: >-
        Represents an error encountered during a request to the Connect API.


        See [Handling
        errors](https://developer.squareup.com/docs/build-basics/handling-errors)
        for more information.
      x-release-status: PUBLIC
      required:
        - category
        - code
      properties:
        category:
          $ref: '#/components/schemas/ErrorCategory'
          description: |-
            The high-level category for the error.
            See [ErrorCategory](#type-errorcategory) for possible values
        code:
          $ref: '#/components/schemas/ErrorCode'
          description: |-
            The specific code of the error.
            See [ErrorCode](#type-errorcode) for possible values
        detail:
          type: string
          description: A human-readable description of the error for debugging purposes.
        field:
          type: string
          description: |-
            The name of the field provided in the original request (if any) that
            the error pertains to.
    ErrorCategory:
      type: string
      enum:
        - API_ERROR
        - AUTHENTICATION_ERROR
        - INVALID_REQUEST_ERROR
        - RATE_LIMIT_ERROR
        - PAYMENT_METHOD_ERROR
        - REFUND_ERROR
        - MERCHANT_SUBSCRIPTION_ERROR
        - EXTERNAL_VENDOR_ERROR
      x-enum-elements:
        - name: API_ERROR
          description: An error occurred with the Connect API itself.
        - name: AUTHENTICATION_ERROR
          description: |-
            An authentication error occurred. Most commonly, the request had
            a missing, malformed, or otherwise invalid `Authorization` header.
        - name: INVALID_REQUEST_ERROR
          description: |-
            The request was invalid. Most commonly, a required parameter was
            missing, or a provided parameter had an invalid value.
        - name: RATE_LIMIT_ERROR
          description: >-
            Your application reached the Square API rate limit. You might
            receive this error if your application sends a high number of
            requests

            to Square APIs in a short period of time.


            Your application should monitor responses for `429 RATE_LIMITED`
            errors and use a retry mechanism with an [exponential
            backoff](https://en.wikipedia.org/wiki/Exponential_backoff)

            schedule to resend the requests at an increasingly slower rate. It
            is also a good practice to use a randomized delay (jitter) in your
            retry schedule.
        - name: PAYMENT_METHOD_ERROR
          description: |-
            An error occurred while processing a payment method. Most commonly,
            the details of the payment method were invalid (such as a card's CVV
            or expiration date).
        - name: REFUND_ERROR
          description: An error occurred while attempting to process a refund.
        - name: MERCHANT_SUBSCRIPTION_ERROR
          description: An error occurred when checking a merchant subscription status
        - name: EXTERNAL_VENDOR_ERROR
          description: An error that is returned from an external vendor's API
      description: |-
        Indicates which high-level category of error has occurred during a
        request to the Connect API.
      x-release-status: PUBLIC
    ErrorCode:
      type: string
      enum:
        - INTERNAL_SERVER_ERROR
        - UNAUTHORIZED
        - ACCESS_TOKEN_EXPIRED
        - ACCESS_TOKEN_REVOKED
        - CLIENT_DISABLED
        - FORBIDDEN
        - INSUFFICIENT_SCOPES
        - APPLICATION_DISABLED
        - V1_APPLICATION
        - V1_ACCESS_TOKEN
        - CARD_PROCESSING_NOT_ENABLED
        - MERCHANT_SUBSCRIPTION_NOT_FOUND
        - BAD_REQUEST
        - MISSING_REQUIRED_PARAMETER
        - INCORRECT_TYPE
        - INVALID_TIME
        - INVALID_TIME_RANGE
        - INVALID_VALUE
        - INVALID_CURSOR
        - UNKNOWN_QUERY_PARAMETER
        - CONFLICTING_PARAMETERS
        - EXPECTED_JSON_BODY
        - INVALID_SORT_ORDER
        - VALUE_REGEX_MISMATCH
        - VALUE_TOO_SHORT
        - VALUE_TOO_LONG
        - VALUE_TOO_LOW
        - VALUE_TOO_HIGH
        - VALUE_EMPTY
        - ARRAY_LENGTH_TOO_LONG
        - ARRAY_LENGTH_TOO_SHORT
        - ARRAY_EMPTY
        - EXPECTED_BOOLEAN
        - EXPECTED_INTEGER
        - EXPECTED_FLOAT
        - EXPECTED_STRING
        - EXPECTED_OBJECT
        - EXPECTED_ARRAY
        - EXPECTED_MAP
        - EXPECTED_BASE64_ENCODED_BYTE_ARRAY
        - INVALID_ARRAY_VALUE
        - INVALID_ENUM_VALUE
        - INVALID_CONTENT_TYPE
        - INVALID_FORM_VALUE
        - CUSTOMER_NOT_FOUND
        - ONE_INSTRUMENT_EXPECTED
        - NO_FIELDS_SET
        - TOO_MANY_MAP_ENTRIES
        - MAP_KEY_LENGTH_TOO_SHORT
        - MAP_KEY_LENGTH_TOO_LONG
        - CUSTOMER_MISSING_NAME
        - CUSTOMER_MISSING_EMAIL
        - INVALID_PAUSE_LENGTH
        - INVALID_DATE
        - UNSUPPORTED_COUNTRY
        - UNSUPPORTED_CURRENCY
        - APPLE_TTP_PIN_TOKEN
        - CARD_EXPIRED
        - INVALID_EXPIRATION
        - INVALID_EXPIRATION_YEAR
        - INVALID_EXPIRATION_DATE
        - UNSUPPORTED_CARD_BRAND
        - UNSUPPORTED_ENTRY_METHOD
        - INVALID_ENCRYPTED_CARD
        - INVALID_CARD
        - PAYMENT_AMOUNT_MISMATCH
        - GENERIC_DECLINE
        - CVV_FAILURE
        - ADDRESS_VERIFICATION_FAILURE
        - INVALID_ACCOUNT
        - CURRENCY_MISMATCH
        - INSUFFICIENT_FUNDS
        - INSUFFICIENT_PERMISSIONS
        - CARDHOLDER_INSUFFICIENT_PERMISSIONS
        - INVALID_LOCATION
        - TRANSACTION_LIMIT
        - VOICE_FAILURE
        - PAN_FAILURE
        - EXPIRATION_FAILURE
        - CARD_NOT_SUPPORTED
        - INVALID_PIN
        - MISSING_PIN
        - MISSING_ACCOUNT_TYPE
        - INVALID_POSTAL_CODE
        - INVALID_FEES
        - MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED
        - PAYMENT_LIMIT_EXCEEDED
        - GIFT_CARD_AVAILABLE_AMOUNT
        - ACCOUNT_UNUSABLE
        - BUYER_REFUSED_PAYMENT
        - DELAYED_TRANSACTION_EXPIRED
        - DELAYED_TRANSACTION_CANCELED
        - DELAYED_TRANSACTION_CAPTURED
        - DELAYED_TRANSACTION_FAILED
        - CARD_TOKEN_EXPIRED
        - CARD_TOKEN_USED
        - AMOUNT_TOO_HIGH
        - UNSUPPORTED_INSTRUMENT_TYPE
        - REFUND_AMOUNT_INVALID
        - REFUND_ALREADY_PENDING
        - PAYMENT_NOT_REFUNDABLE
        - PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE
        - REFUND_DECLINED
        - INSUFFICIENT_PERMISSIONS_FOR_REFUND
        - INVALID_CARD_DATA
        - SOURCE_USED
        - SOURCE_EXPIRED
        - UNSUPPORTED_LOYALTY_REWARD_TIER
        - LOCATION_MISMATCH
        - IDEMPOTENCY_KEY_REUSED
        - UNEXPECTED_VALUE
        - SANDBOX_NOT_SUPPORTED
        - INVALID_EMAIL_ADDRESS
        - INVALID_PHONE_NUMBER
        - CHECKOUT_EXPIRED
        - BAD_CERTIFICATE
        - INVALID_SQUARE_VERSION_FORMAT
        - API_VERSION_INCOMPATIBLE
        - CARD_PRESENCE_REQUIRED
        - UNSUPPORTED_SOURCE_TYPE
        - CARD_MISMATCH
        - PLAID_ERROR
        - PLAID_ERROR_ITEM_LOGIN_REQUIRED
        - PLAID_ERROR_RATE_LIMIT
        - CARD_DECLINED
        - VERIFY_CVV_FAILURE
        - VERIFY_AVS_FAILURE
        - CARD_DECLINED_CALL_ISSUER
        - CARD_DECLINED_VERIFICATION_REQUIRED
        - BAD_EXPIRATION
        - CHIP_INSERTION_REQUIRED
        - ALLOWABLE_PIN_TRIES_EXCEEDED
        - RESERVATION_DECLINED
        - UNKNOWN_BODY_PARAMETER
        - NOT_FOUND
        - APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND
        - METHOD_NOT_ALLOWED
        - NOT_ACCEPTABLE
        - REQUEST_TIMEOUT
        - CONFLICT
        - GONE
        - REQUEST_ENTITY_TOO_LARGE
        - UNSUPPORTED_MEDIA_TYPE
        - UNPROCESSABLE_ENTITY
        - RATE_LIMITED
        - NOT_IMPLEMENTED
        - BAD_GATEWAY
        - SERVICE_UNAVAILABLE
        - TEMPORARY_ERROR
        - GATEWAY_TIMEOUT
      x-enum-elements:
        - name: INTERNAL_SERVER_ERROR
          description: A general server error occurred.
          error-category: API_ERROR
        - name: UNAUTHORIZED
          description: A general authorization error occurred.
          error-category: AUTHENTICATION_ERROR
        - name: ACCESS_TOKEN_EXPIRED
          description: The provided access token has expired.
          error-category: AUTHENTICATION_ERROR
        - name: ACCESS_TOKEN_REVOKED
          description: The provided access token has been revoked.
          error-category: AUTHENTICATION_ERROR
        - name: CLIENT_DISABLED
          description: The provided client has been disabled.
          error-category: AUTHENTICATION_ERROR
        - name: FORBIDDEN
          description: A general access error occurred.
          error-category: AUTHENTICATION_ERROR
        - name: INSUFFICIENT_SCOPES
          description: |-
            The provided access token does not have permission
            to execute the requested action.
          error-category: AUTHENTICATION_ERROR
        - name: APPLICATION_DISABLED
          description: The calling application was disabled.
          error-category: INVALID_REQUEST_ERROR
        - name: V1_APPLICATION
          description: |-
            The calling application was created prior to
            2016-03-30 and is not compatible with v2 Square API calls.
          error-category: INVALID_REQUEST_ERROR
        - name: V1_ACCESS_TOKEN
          description: |-
            The calling application is using an access token
            created prior to 2016-03-30 and is not compatible with v2 Square API
            calls.
          error-category: INVALID_REQUEST_ERROR
        - name: CARD_PROCESSING_NOT_ENABLED
          description: |-
            The location provided in the API call is not
            enabled for credit card processing.
          error-category: INVALID_REQUEST_ERROR
        - name: MERCHANT_SUBSCRIPTION_NOT_FOUND
          description: A required subscription was not found for the merchant
          error-category: MERCHANT_SUBSCRIPTION_ERROR
        - name: BAD_REQUEST
          description: A general error occurred with the request.
          error-category: INVALID_REQUEST_ERROR
        - name: MISSING_REQUIRED_PARAMETER
          description: |-
            The request is missing a required path, query, or
            body parameter.
          error-category: INVALID_REQUEST_ERROR
        - name: INCORRECT_TYPE
          description: |-
            The value provided in the request is the wrong
            type. For example, a string instead of an integer.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_TIME
          description: |-
            Formatting for the provided time value is
            incorrect.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_TIME_RANGE
          description: |-
            The time range provided in the request is invalid.
            For example, the end time is before the start time.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_VALUE
          description: |-
            The provided value is invalid. For example,
            including `%` in a phone number.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_CURSOR
          description: |-
            The pagination cursor included in the request is
            invalid.
          error-category: INVALID_REQUEST_ERROR
        - name: UNKNOWN_QUERY_PARAMETER
          description: |-
            The query parameters provided is invalid for the
            requested endpoint.
          error-category: INVALID_REQUEST_ERROR
        - name: CONFLICTING_PARAMETERS
          description: |-
            One or more of the request parameters conflict with
            each other.
          error-category: INVALID_REQUEST_ERROR
        - name: EXPECTED_JSON_BODY
          description: The request body is not a JSON object.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_SORT_ORDER
          description: |-
            The provided sort order is not a valid key.
            Currently, sort order must be `ASC` or `DESC`.
          error-category: INVALID_REQUEST_ERROR
        - name: VALUE_REGEX_MISMATCH
          description: |-
            The provided value does not match an expected
            regular expression.
          error-category: INVALID_REQUEST_ERROR
        - name: VALUE_TOO_SHORT
          description: |-
            The provided string value is shorter than the
            minimum length allowed.
          error-category: INVALID_REQUEST_ERROR
        - name: VALUE_TOO_LONG
          description: |-
            The provided string value is longer than the
            maximum length allowed.
          error-category: INVALID_REQUEST_ERROR
        - name: VALUE_TOO_LOW
          description: |-
            The provided value is less than the supported
            minimum.
          error-category: INVALID_REQUEST_ERROR
        - name: VALUE_TOO_HIGH
          description: |-
            The provided value is greater than the supported
            maximum.
          error-category: INVALID_REQUEST_ERROR
        - name: VALUE_EMPTY
          description: |-
            The provided value has a default (empty) value
            such as a blank string.
          error-category: INVALID_REQUEST_ERROR
        - name: ARRAY_LENGTH_TOO_LONG
          description: The provided array has too many elements.
          error-category: INVALID_REQUEST_ERROR
        - name: ARRAY_LENGTH_TOO_SHORT
          description: The provided array has too few elements.
          error-category: INVALID_REQUEST_ERROR
        - name: ARRAY_EMPTY
          description: The provided array is empty.
          error-category: INVALID_REQUEST_ERROR
        - name: EXPECTED_BOOLEAN
          description: |-
            The endpoint expected the provided value to be a
            boolean.
          error-category: INVALID_REQUEST_ERROR
        - name: EXPECTED_INTEGER
          description: |-
            The endpoint expected the provided value to be an
            integer.
          error-category: INVALID_REQUEST_ERROR
        - name: EXPECTED_FLOAT
          description: |-
            The endpoint expected the provided value to be a
            float.
          error-category: INVALID_REQUEST_ERROR
        - name: EXPECTED_STRING
          description: |-
            The endpoint expected the provided value to be a
            string.
          error-category: INVALID_REQUEST_ERROR
        - name: EXPECTED_OBJECT
          description: |-
            The endpoint expected the provided value to be a
            JSON object.
          error-category: INVALID_REQUEST_ERROR
        - name: EXPECTED_ARRAY
          description: |-
            The endpoint expected the provided value to be an
            array or list.
          error-category: INVALID_REQUEST_ERROR
        - name: EXPECTED_MAP
          description: |-
            The endpoint expected the provided value to be a
            map or associative array.
          error-category: INVALID_REQUEST_ERROR
        - name: EXPECTED_BASE64_ENCODED_BYTE_ARRAY
          description: |-
            The endpoint expected the provided value to be an
            array encoded in base64.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_ARRAY_VALUE
          description: |-
            One or more objects in the array does not match the
            array type.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_ENUM_VALUE
          description: |-
            The provided static string is not valid for the
            field.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_CONTENT_TYPE
          description: Invalid content type header.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_FORM_VALUE
          description: |-
            Only relevant for applications created prior to
            2016-03-30. Indicates there was an error while parsing form values.
          error-category: INVALID_REQUEST_ERROR
        - name: CUSTOMER_NOT_FOUND
          description: >-
            The provided customer id can't be found in the merchant's customers
            list.
          error-category: INVALID_REQUEST_ERROR
        - name: ONE_INSTRUMENT_EXPECTED
          description: A general error occurred.
          error-category: INVALID_REQUEST_ERROR
        - name: NO_FIELDS_SET
          description: A general error occurred.
          error-category: INVALID_REQUEST_ERROR
        - name: TOO_MANY_MAP_ENTRIES
          description: Too many entries in the map field.
          error-category: INVALID_REQUEST_ERROR
        - name: MAP_KEY_LENGTH_TOO_SHORT
          description: The length of one of the provided keys in the map is too short.
          error-category: INVALID_REQUEST_ERROR
        - name: MAP_KEY_LENGTH_TOO_LONG
          description: The length of one of the provided keys in the map is too long.
          error-category: INVALID_REQUEST_ERROR
        - name: CUSTOMER_MISSING_NAME
          description: The provided customer does not have a recorded name.
          error-category: INVALID_REQUEST_ERROR
        - name: CUSTOMER_MISSING_EMAIL
          description: The provided customer does not have a recorded email.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_PAUSE_LENGTH
          description: >-
            The subscription cannot be paused longer than the duration of the
            current phase.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_DATE
          description: The subscription cannot be paused/resumed on the given date.
          error-category: INVALID_REQUEST_ERROR
        - name: UNSUPPORTED_COUNTRY
          description: The API request references an unsupported country.
          error-category: INVALID_REQUEST_ERROR
        - name: UNSUPPORTED_CURRENCY
          description: The API request references an unsupported currency.
          error-category: INVALID_REQUEST_ERROR
        - name: APPLE_TTP_PIN_TOKEN
          description: >-
            The payment was declined by the card issuer during an Apple Tap to
            Pay (TTP)

            transaction with a request for the card's PIN. This code will be
            returned alongside

            `CARD_DECLINED_VERIFICATION_REQUIRED` as a supplemental error, and
            will include an

            issuer-provided token in the `details` field that is needed to
            initiate the PIN

            collection flow on the iOS device.
          error-category: PAYMENT_METHOD_ERROR
        - name: CARD_EXPIRED
          description: The card issuer declined the request because the card is expired.
          error-category: PAYMENT_METHOD_ERROR
        - name: INVALID_EXPIRATION
          description: |-
            The expiration date for the payment card is invalid. For example,
            it indicates a date in the past.
          error-category: PAYMENT_METHOD_ERROR
        - name: INVALID_EXPIRATION_YEAR
          description: |-
            The expiration year for the payment card is invalid. For example,
            it indicates a year in the past or contains invalid characters.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_EXPIRATION_DATE
          description: |-
            The expiration date for the payment card is invalid. For example,
            it contains invalid characters.
          error-category: INVALID_REQUEST_ERROR
        - name: UNSUPPORTED_CARD_BRAND
          description: The credit card provided is not from a supported issuer.
          error-category: PAYMENT_METHOD_ERROR
        - name: UNSUPPORTED_ENTRY_METHOD
          description: >-
            The entry method for the credit card (swipe, dip, tap) is not
            supported.
          error-category: PAYMENT_METHOD_ERROR
        - name: INVALID_ENCRYPTED_CARD
          description: The encrypted card information is invalid.
          error-category: PAYMENT_METHOD_ERROR
        - name: INVALID_CARD
          description: The credit card cannot be validated based on the provided details.
          error-category: PAYMENT_METHOD_ERROR
        - name: PAYMENT_AMOUNT_MISMATCH
          description: >-
            The payment was declined because there was a payment amount
            mismatch.

            The money amount Square was expecting does not match the amount
            provided.
          error-category: PAYMENT_METHOD_ERROR
        - name: GENERIC_DECLINE
          description: >-
            Square received a decline without any additional information.

            If the payment information seems correct, the buyer can contact
            their

            issuer to ask for more information.
          error-category: PAYMENT_METHOD_ERROR
        - name: CVV_FAILURE
          description: >-
            The card issuer declined the request because the CVV value is
            invalid.
          error-category: PAYMENT_METHOD_ERROR
        - name: ADDRESS_VERIFICATION_FAILURE
          description: >-
            The card issuer declined the request because the postal code is
            invalid.
          error-category: PAYMENT_METHOD_ERROR
        - name: INVALID_ACCOUNT
          description: The issuer was not able to locate the account on record.
          error-category: PAYMENT_METHOD_ERROR
        - name: CURRENCY_MISMATCH
          description: >-
            The currency associated with the payment is not valid for the
            provided

            funding source. For example, a gift card funded in USD cannot be
            used to process

            payments in GBP.
          error-category: PAYMENT_METHOD_ERROR
        - name: INSUFFICIENT_FUNDS
          description: The funding source has insufficient funds to cover the payment.
          error-category: PAYMENT_METHOD_ERROR
        - name: INSUFFICIENT_PERMISSIONS
          description: |-
            The Square account does not have the permissions to accept
            this payment. For example, Square may limit which merchants are
            allowed to receive gift card payments.
          error-category: PAYMENT_METHOD_ERROR
        - name: CARDHOLDER_INSUFFICIENT_PERMISSIONS
          description: >-
            The card issuer has declined the transaction due to restrictions on
            where the card can be used.

            For example, a gift card is limited to a single merchant.
          error-category: PAYMENT_METHOD_ERROR
        - name: INVALID_LOCATION
          description: >-
            The Square account cannot take payments in the specified region.

            A Square account can take payments only from the region where the
            account was created.
          error-category: PAYMENT_METHOD_ERROR
        - name: TRANSACTION_LIMIT
          description: >-
            The card issuer has determined the payment amount is either too high
            or too low.

            The API returns the error code mostly for credit cards (for example,
            the card reached

            the credit limit). However, sometimes the issuer bank can indicate
            the error for debit

            or prepaid cards (for example, card has insufficient funds).
          error-category: PAYMENT_METHOD_ERROR
        - name: VOICE_FAILURE
          description: >-
            The card issuer declined the request because the issuer requires
            voice authorization from the cardholder. The seller should ask the
            customer to contact the card issuing bank to authorize the payment.
          error-category: PAYMENT_METHOD_ERROR
        - name: PAN_FAILURE
          description: |-
            The specified card number is invalid. For example, it is of
            incorrect length or is incorrectly formatted.
          error-category: PAYMENT_METHOD_ERROR
        - name: EXPIRATION_FAILURE
          description: |-
            The card expiration date is either invalid or indicates that the
            card is expired.
          error-category: PAYMENT_METHOD_ERROR
        - name: CARD_NOT_SUPPORTED
          description: >-
            The card is not supported either in the geographic region or by

            the [merchant category
            code](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code)
            (MCC).
          error-category: PAYMENT_METHOD_ERROR
        - name: INVALID_PIN
          description: The card issuer declined the request because the PIN is invalid.
          error-category: PAYMENT_METHOD_ERROR
        - name: MISSING_PIN
          description: The payment is missing a required PIN.
          error-category: PAYMENT_METHOD_ERROR
        - name: MISSING_ACCOUNT_TYPE
          description: The payment is missing a required ACCOUNT_TYPE parameter.
          error-category: PAYMENT_METHOD_ERROR
        - name: INVALID_POSTAL_CODE
          description: The postal code is incorrectly formatted.
          error-category: PAYMENT_METHOD_ERROR
        - name: INVALID_FEES
          description: The app_fee_money on a payment is too high.
          error-category: PAYMENT_METHOD_ERROR
        - name: MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED
          description: >-
            The card must be swiped, tapped, or dipped. Payments attempted by
            manually entering the card number are declined.
          error-category: PAYMENT_METHOD_ERROR
        - name: PAYMENT_LIMIT_EXCEEDED
          description: >-
            Square declined the request because the payment amount exceeded the
            processing limit for this merchant.
          error-category: PAYMENT_METHOD_ERROR
        - name: GIFT_CARD_AVAILABLE_AMOUNT
          description: >-
            When a Gift Card is a payment source, you can allow taking a partial
            payment

            by adding the `accept_partial_authorization` parameter in the
            request.

            However, taking such a partial payment does not work if your request
            also includes

            `tip_money`, `app_fee_money`, or both. Square declines such payments
            and returns

            the `GIFT_CARD_AVAILABLE_AMOUNT` error.

            For more information, see

            [CreatePayment errors (additional
            information)](https://developer.squareup.com/docs/payments-api/error-codes#createpayment-errors-additional-information).
          error-category: PAYMENT_METHOD_ERROR
        - name: ACCOUNT_UNUSABLE
          description: The account provided cannot carry out transactions.
          error-category: PAYMENT_METHOD_ERROR
        - name: BUYER_REFUSED_PAYMENT
          description: Bank account rejected or was not authorized for the payment.
          error-category: PAYMENT_METHOD_ERROR
        - name: DELAYED_TRANSACTION_EXPIRED
          description: >-
            The application tried to update a delayed-capture payment that has
            expired.
          error-category: INVALID_REQUEST_ERROR
        - name: DELAYED_TRANSACTION_CANCELED
          description: >-
            The application tried to cancel a delayed-capture payment that was
            already cancelled.
          error-category: INVALID_REQUEST_ERROR
        - name: DELAYED_TRANSACTION_CAPTURED
          description: >-
            The application tried to capture a delayed-capture payment that was
            already captured.
          error-category: INVALID_REQUEST_ERROR
        - name: DELAYED_TRANSACTION_FAILED
          description: >-
            The application tried to update a delayed-capture payment that
            failed.
          error-category: INVALID_REQUEST_ERROR
        - name: CARD_TOKEN_EXPIRED
          description: The provided card token (nonce) has expired.
          error-category: INVALID_REQUEST_ERROR
        - name: CARD_TOKEN_USED
          description: >-
            The provided card token (nonce) was already used to process the
            payment or refund.
          error-category: INVALID_REQUEST_ERROR
        - name: AMOUNT_TOO_HIGH
          description: >-
            The requested payment amount is too high for the provided payment
            source.
          error-category: INVALID_REQUEST_ERROR
        - name: UNSUPPORTED_INSTRUMENT_TYPE
          description: The API request references an unsupported instrument type.
          error-category: INVALID_REQUEST_ERROR
        - name: REFUND_AMOUNT_INVALID
          description: The requested refund amount exceeds the amount available to refund.
          error-category: REFUND_ERROR
        - name: REFUND_ALREADY_PENDING
          description: The payment already has a pending refund.
          error-category: REFUND_ERROR
        - name: PAYMENT_NOT_REFUNDABLE
          description: >-
            The payment is not refundable. For example, the payment is too old
            to be refunded.
          error-category: REFUND_ERROR
        - name: PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE
          description: The payment is not refundable because it has been disputed.
          error-category: REFUND_ERROR
        - name: REFUND_DECLINED
          description: Request failed - The card issuer declined the refund.
          error-category: REFUND_ERROR
        - name: INSUFFICIENT_PERMISSIONS_FOR_REFUND
          description: >-
            The Square account does not have the permissions to process this
            refund.
          error-category: REFUND_ERROR
        - name: INVALID_CARD_DATA
          description: Generic error - the provided card data is invalid.
          error-category: INVALID_REQUEST_ERROR
        - name: SOURCE_USED
          description: The provided source id was already used to create a card.
          error-category: INVALID_REQUEST_ERROR
        - name: SOURCE_EXPIRED
          description: The provided source id has expired.
          error-category: INVALID_REQUEST_ERROR
        - name: UNSUPPORTED_LOYALTY_REWARD_TIER
          description: |-
            The referenced loyalty program reward tier is not supported.
            This could happen if the reward tier created in a first party
            application is incompatible with the Loyalty API.
          error-category: INVALID_REQUEST_ERROR
        - name: LOCATION_MISMATCH
          description: >-
            Generic error - the given location does not matching what is
            expected.
          error-category: INVALID_REQUEST_ERROR
        - name: IDEMPOTENCY_KEY_REUSED
          description: The provided idempotency key has already been used.
          error-category: INVALID_REQUEST_ERROR
        - name: UNEXPECTED_VALUE
          description: General error - the value provided was unexpected.
          error-category: INVALID_REQUEST_ERROR
        - name: SANDBOX_NOT_SUPPORTED
          description: The API request is not supported in sandbox.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_EMAIL_ADDRESS
          description: The provided email address is invalid.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_PHONE_NUMBER
          description: The provided phone number is invalid.
          error-category: INVALID_REQUEST_ERROR
        - name: CHECKOUT_EXPIRED
          description: The provided checkout URL has expired.
          error-category: INVALID_REQUEST_ERROR
        - name: BAD_CERTIFICATE
          description: Bad certificate.
          error-category: INVALID_REQUEST_ERROR
        - name: INVALID_SQUARE_VERSION_FORMAT
          description: The provided Square-Version is incorrectly formatted.
          error-category: INVALID_REQUEST_ERROR
        - name: API_VERSION_INCOMPATIBLE
          description: >-
            The provided Square-Version is incompatible with the requested
            action.
          error-category: INVALID_REQUEST_ERROR
        - name: CARD_PRESENCE_REQUIRED
          description: The transaction requires that a card be present.
          error-category: INVALID_REQUEST_ERROR
        - name: UNSUPPORTED_SOURCE_TYPE
          description: The API request references an unsupported source type.
          error-category: INVALID_REQUEST_ERROR
        - name: CARD_MISMATCH
          description: The provided card does not match what is expected.
          error-category: REFUND_ERROR
        - name: PLAID_ERROR
          description: Generic plaid error
          error-category: EXTERNAL_VENDOR_ERROR
        - name: PLAID_ERROR_ITEM_LOGIN_REQUIRED
          description: Plaid error - ITEM_LOGIN_REQUIRED
          error-category: EXTERNAL_VENDOR_ERROR
        - name: PLAID_ERROR_RATE_LIMIT
          description: Plaid error - RATE_LIMIT
          error-category: EXTERNAL_VENDOR_ERROR
        - name: CARD_DECLINED
          description: The card was declined.
          error-category: PAYMENT_METHOD_ERROR
        - name: VERIFY_CVV_FAILURE
          description: The CVV could not be verified.
          error-category: PAYMENT_METHOD_ERROR
        - name: VERIFY_AVS_FAILURE
          description: The AVS could not be verified.
          error-category: PAYMENT_METHOD_ERROR
        - name: CARD_DECLINED_CALL_ISSUER
          description: |-
            The payment card was declined with a request
            for the card holder to call the issuer.
          error-category: PAYMENT_METHOD_ERROR
        - name: CARD_DECLINED_VERIFICATION_REQUIRED
          description: |-
            The payment card was declined with a request
            for additional verification.
          error-category: PAYMENT_METHOD_ERROR
        - name: BAD_EXPIRATION
          description: |-
            The card expiration date is either missing or
            incorrectly formatted.
          error-category: PAYMENT_METHOD_ERROR
        - name: CHIP_INSERTION_REQUIRED
          description: |-
            The card issuer requires that the card be read
            using a chip reader.
          error-category: PAYMENT_METHOD_ERROR
        - name: ALLOWABLE_PIN_TRIES_EXCEEDED
          description: >-
            The card has exhausted its available pin entry

            retries set by the card issuer. Resolving the error typically
            requires the

            card holder to contact the card issuer.
          error-category: PAYMENT_METHOD_ERROR
        - name: RESERVATION_DECLINED
          description: The card issuer declined the refund.
          error-category: REFUND_ERROR
        - name: UNKNOWN_BODY_PARAMETER
          description: The body parameter is not recognized by the requested endpoint.
          error-category: INVALID_REQUEST_ERROR
        - name: NOT_FOUND
          description: Not Found - a general error occurred.
          error-category: INVALID_REQUEST_ERROR
        - name: APPLE_PAYMENT_PROCESSING_CERTIFICATE_HASH_NOT_FOUND
          description: Square could not find the associated Apple Pay certificate.
          error-category: INVALID_REQUEST_ERROR
        - name: METHOD_NOT_ALLOWED
          description: Method Not Allowed - a general error occurred.
          error-category: INVALID_REQUEST_ERROR
        - name: NOT_ACCEPTABLE
          description: Not Acceptable - a general error occurred.
          error-category: INVALID_REQUEST_ERROR
        - name: REQUEST_TIMEOUT
          description: Request Timeout - a general error occurred.
          error-category: INVALID_REQUEST_ERROR
        - name: CONFLICT
          description: Conflict - a general error occurred.
          error-category: INVALID_REQUEST_ERROR
        - name: GONE
          description: |-
            The target resource is no longer available and this
            condition is likely to be permanent.
          error-category: INVALID_REQUEST_ERROR
        - name: REQUEST_ENTITY_TOO_LARGE
          description: Request Entity Too Large - a general error occurred.
          error-category: INVALID_REQUEST_ERROR
        - name: UNSUPPORTED_MEDIA_TYPE
          description: Unsupported Media Type - a general error occurred.
          error-category: INVALID_REQUEST_ERROR
        - name: UNPROCESSABLE_ENTITY
          description: Unprocessable Entity - a general error occurred.
          error-category: INVALID_REQUEST_ERROR
        - name: RATE_LIMITED
          description: Rate Limited - a general error occurred.
          error-category: RATE_LIMIT_ERROR
        - name: NOT_IMPLEMENTED
          description: Not Implemented - a general error occurred.
          error-category: API_ERROR
        - name: BAD_GATEWAY
          description: Bad Gateway - a general error occurred.
          error-category: API_ERROR
        - name: SERVICE_UNAVAILABLE
          description: Service Unavailable - a general error occurred.
          error-category: API_ERROR
        - name: TEMPORARY_ERROR
          description: |-
            A temporary internal error occurred. You can safely retry your call
            using the same idempotency key.
          error-category: PAYMENT_METHOD_ERROR
        - name: GATEWAY_TIMEOUT
          description: Gateway Timeout - a general error occurred.
          error-category: API_ERROR
      description: |-
        Indicates the specific error that occurred during a request to a
        Square API.
      x-release-status: PUBLIC
    Event:
      type: object
      x-release-status: PUBLIC
      properties:
        merchant_id:
          type: string
          description: The ID of the target merchant associated with the event.
          nullable: true
        location_id:
          type: string
          description: The ID of the target location associated with the event.
          nullable: true
        type:
          type: string
          description: The type of event this represents.
          nullable: true
        event_id:
          type: string
          description: A unique ID for the event.
          nullable: true
        created_at:
          type: string
          description: Timestamp of when the event was created, in RFC 3339 format.
          readOnly: true
        data:
          $ref: '#/components/schemas/EventData'
          description: The data associated with the event.
          nullable: true
    EventData:
      type: object
      x-release-status: PUBLIC
      properties:
        type:
          type: string
          description: The name of the affected objects type.
          nullable: true
        id:
          type: string
          description: The ID of the affected object.
        deleted:
          type: boolean
          description: >-
            This is true if the affected object has been deleted; otherwise,
            it's absent.
          nullable: true
        object:
          type: object
          description: >-
            An object containing fields and values relevant to the event. It is
            absent if the affected object has been deleted.
          nullable: true
    EventMetadata:
      type: object
      description: Contains metadata about a particular [Event](entity:Event).
      x-release-status: BETA
      properties:
        event_id:
          type: string
          description: A unique ID for the event.
          nullable: true
        api_version:
          type: string
          description: >-
            The API version of the event. This corresponds to the default API
            version of the developer application at the time when the event was
            created.
          nullable: true
    EventTypeMetadata:
      type: object
      description: Contains the metadata of a webhook event type.
      x-release-status: PUBLIC
      properties:
        event_type:
          type: string
          description: The event type.
          readOnly: true
        api_version_introduced:
          type: string
          description: The API version at which the event type was introduced.
          readOnly: true
        release_status:
          type: string
          description: The release status of the event type.
          readOnly: true
    ExcludeStrategy:
      type: string
      enum:
        - LEAST_EXPENSIVE
        - MOST_EXPENSIVE
      x-enum-elements:
        - name: LEAST_EXPENSIVE
          description: >-
            The least expensive matched products are excluded from the pricing.
            If

            the pricing rule is set to exclude one product and multiple products
            in the

            match set qualify as least expensive, then one will be excluded at
            random.


            Excluding the least expensive product gives the best discount value
            to the buyer.
        - name: MOST_EXPENSIVE
          description: >-
            The most expensive matched product is excluded from the pricing
            rule.

            If multiple products have the same price and all qualify as least
            expensive,

            one will be excluded at random.


            This guarantees that the most expensive product is purchased at full
            price.
      description: |-
        Indicates which products matched by a CatalogPricingRule
        will be excluded if the pricing rule uses an exclude set.
      x-release-status: BETA
    ExternalPaymentDetails:
      type: object
      description: >-
        Stores details about an external payment. Contains only non-confidential
        information.

        For more information, see 

        [Take External
        Payments](https://developer.squareup.com/docs/payments-api/take-payments/external-payments).
      x-release-status: PUBLIC
      required:
        - type
        - source
      properties:
        type:
          type: string
          description: >-
            The type of external payment the seller received. It can be one of
            the following:

            - CHECK - Paid using a physical check.

            - BANK_TRANSFER - Paid using external bank transfer.

            - OTHER\_GIFT\_CARD - Paid using a non-Square gift card.

            - CRYPTO - Paid using a crypto currency.

            - SQUARE_CASH - Paid using Square Cash App.

            - SOCIAL - Paid using peer-to-peer payment applications.

            - EXTERNAL - A third-party application gathered this payment outside
            of Square.

            - EMONEY - Paid using an E-money provider.

            - CARD - A credit or debit card that Square does not support.

            - STORED_BALANCE - Use for house accounts, store credit, and so
            forth.

            - FOOD_VOUCHER - Restaurant voucher provided by employers to
            employees to pay for meals

            - OTHER - A type not listed here.
          maxLength: 50
        source:
          type: string
          description: |-
            A description of the external payment source. For example, 
            "Food Delivery Service".
          maxLength: 255
        source_id:
          type: string
          description: An ID to associate the payment to its originating source.
          maxLength: 255
          nullable: true
        source_fee_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The fees paid to the source. The `amount_money` minus this field is 
            the net amount seller receives.
          nullable: true
    FilterValue:
      type: object
      description: >-
        A filter to select resources based on an exact field value. For any
        given

        value, the value can only be in one property. Depending on the field,
        either

        all properties can be set or only a subset will be available.


        Refer to the documentation of the field.
      x-release-status: BETA
      properties:
        all:
          type: array
          items:
            type: string
          description: A list of terms that must be present on the field of the resource.
          nullable: true
        any:
          type: array
          items:
            type: string
          description: |-
            A list of terms where at least one of them must be present on the
            field of the resource.
          nullable: true
        none:
          type: array
          items:
            type: string
          description: A list of terms that must not be present on the field the resource
          nullable: true
    FloatNumberRange:
      type: object
      description: Specifies a decimal number range.
      x-release-status: PUBLIC
      properties:
        start_at:
          type: string
          description: A decimal value indicating where the range starts.
          nullable: true
        end_at:
          type: string
          description: A decimal value indicating where the range ends.
          nullable: true
    Fulfillment:
      type: object
      description: >-
        Contains details about how to fulfill this order.

        Orders can only be created with at most one fulfillment using the API.

        However, orders returned by the Orders API might contain multiple
        fulfillments because sellers can create multiple fulfillments using
        Square products such as Square Online.
      x-release-status: PUBLIC
      properties:
        uid:
          type: string
          description: A unique ID that identifies the fulfillment only within this order.
          maxLength: 60
          x-release-status: BETA
          nullable: true
        type:
          $ref: '#/components/schemas/FulfillmentType'
          description: |-
            The type of the fulfillment.
            See [FulfillmentType](#type-fulfillmenttype) for possible values
          nullable: true
        state:
          $ref: '#/components/schemas/FulfillmentState'
          description: |-
            The state of the fulfillment.
            See [FulfillmentState](#type-fulfillmentstate) for possible values
          nullable: true
        line_item_application:
          $ref: '#/components/schemas/FulfillmentFulfillmentLineItemApplication'
          description: >-
            Describes what order line items this fulfillment applies to.

            It can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment
            entries.

            See
            [FulfillmentFulfillmentLineItemApplication](#type-fulfillmentfulfillmentlineitemapplication)
            for possible values
          readOnly: true
          x-release-status: BETA
        entries:
          type: array
          items:
            $ref: '#/components/schemas/FulfillmentFulfillmentEntry'
          description: >-
            A list of entries pertaining to the fulfillment of an order. Each
            entry must reference

            a valid `uid` for an order line item in the `line_item_uid` field,
            as well as a `quantity` to

            fulfill.


            Multiple entries can reference the same line item `uid`, as long as
            the total quantity among

            all fulfillment entries referencing a single line item does not
            exceed the quantity of the

            order's line item itself.


            An order cannot be marked as `COMPLETED` before all fulfillments are
            `COMPLETED`,

            `CANCELED`, or `FAILED`. Fulfillments can be created and completed
            independently

            before order completion.
          readOnly: true
          x-release-status: BETA
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Application-defined data attached to this fulfillment. 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).
          x-release-status: BETA
          nullable: true
        pickup_details:
          $ref: '#/components/schemas/FulfillmentPickupDetails'
          description: >-
            Contains details for a pickup fulfillment. These details are
            required when the fulfillment

            type is `PICKUP`.
          nullable: true
        shipment_details:
          $ref: '#/components/schemas/FulfillmentShipmentDetails'
          description: >-
            Contains details for a shipment fulfillment. These details are
            required when the fulfillment type

            is `SHIPMENT`.


            A shipment fulfillment's relationship to fulfillment `state`:

            `PROPOSED`: A shipment is requested.

            `RESERVED`: Fulfillment in progress. Shipment processing.

            `PREPARED`: Shipment packaged. Shipping label created.

            `COMPLETED`: Package has been shipped.

            `CANCELED`: Shipment has been canceled.

            `FAILED`: Shipment has failed.
          x-release-status: BETA
          nullable: true
        delivery_details:
          $ref: '#/components/schemas/FulfillmentDeliveryDetails'
          description: Describes delivery details of an order fulfillment.
          x-release-status: BETA
          nullable: true
    FulfillmentDeliveryDetails:
      type: object
      description: Describes delivery details of an order fulfillment.
      x-release-status: BETA
      properties:
        recipient:
          $ref: '#/components/schemas/FulfillmentRecipient'
          description: The contact information for the person to receive the fulfillment.
          nullable: true
        schedule_type:
          $ref: >-
            #/components/schemas/FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType
          description: >-
            Indicates the fulfillment delivery schedule type. If `SCHEDULED`,
            then

            `deliver_at` is required. If `ASAP`, then `prep_time_duration` is
            required. The default is `SCHEDULED`.

            See
            [OrderFulfillmentDeliveryDetailsScheduleType](#type-orderfulfillmentdeliverydetailsscheduletype)
            for possible values
          nullable: true
        placed_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was placed.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").


            Must be in RFC 3339 timestamp format, e.g.,
            "2016-09-04T23:59:33.123Z".
          readOnly: true
        deliver_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            that represents the start of the delivery period.

            When the fulfillment `schedule_type` is `ASAP`, the field is
            automatically

            set to the current time plus the `prep_time_duration`.

            Otherwise, the application can set this field while the fulfillment
            `state` is

            `PROPOSED`, `RESERVED`, or `PREPARED` (any time before the

            terminal state such as `COMPLETED`, `CANCELED`, and `FAILED`).


            The timestamp must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          nullable: true
        prep_time_duration:
          type: string
          description: >-
            The duration of time it takes to prepare and deliver this
            fulfillment.

            The duration must be in RFC 3339 format (for example, "P1W3D").
          nullable: true
        delivery_window_duration:
          type: string
          description: >-
            The time period after `deliver_at` in which to deliver the order.

            Applications can set this field when the fulfillment `state` is

            `PROPOSED`, `RESERVED`, or `PREPARED` (any time before the terminal
            state

            such as `COMPLETED`, `CANCELED`, and `FAILED`).


            The duration must be in RFC 3339 format (for example, "P1W3D").
          nullable: true
        note:
          type: string
          description: >-
            Provides additional instructions about the delivery fulfillment.

            It is displayed in the Square Point of Sale application and set by
            the API.
          maxLength: 550
          nullable: true
        completed_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicates when the seller completed the fulfillment.

            This field is automatically set when  fulfillment `state` changes to
            `COMPLETED`.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          nullable: true
        in_progress_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicates when the seller started processing the fulfillment.

            This field is automatically set when the fulfillment `state` changes
            to `RESERVED`.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          readOnly: true
        rejected_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was rejected. This field is

            automatically set when the fulfillment `state` changes to `FAILED`.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          readOnly: true
        ready_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the seller marked the fulfillment as ready for

            courier pickup. This field is automatically set when the fulfillment
            `state` changes

            to PREPARED.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          readOnly: true
        delivered_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was delivered to the recipient.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          readOnly: true
        canceled_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was canceled. This field is
            automatically

            set when the fulfillment `state` changes to `CANCELED`.


            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          readOnly: true
        cancel_reason:
          type: string
          description: 'The delivery cancellation reason. Max length: 100 characters.'
          maxLength: 100
          nullable: true
        courier_pickup_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when an order can be picked up by the courier for
            delivery.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          nullable: true
        courier_pickup_window_duration:
          type: string
          description: >-
            The time period after `courier_pickup_at` in which the courier
            should pick up the order.

            The duration must be in RFC 3339 format (for example, "P1W3D").
          nullable: true
        is_no_contact_delivery:
          type: boolean
          description: Whether the delivery is preferred to be no contact.
          nullable: true
        dropoff_notes:
          type: string
          description: >-
            A note to provide additional instructions about how to deliver the
            order.
          maxLength: 550
          nullable: true
        courier_provider_name:
          type: string
          description: The name of the courier provider.
          maxLength: 255
          nullable: true
        courier_support_phone_number:
          type: string
          description: The support phone number of the courier.
          maxLength: 17
          nullable: true
        square_delivery_id:
          type: string
          description: The identifier for the delivery created by Square.
          maxLength: 50
          nullable: true
        external_delivery_id:
          type: string
          description: >-
            The identifier for the delivery created by the third-party courier
            service.
          maxLength: 50
          nullable: true
        managed_delivery:
          type: boolean
          description: >-
            The flag to indicate the delivery is managed by a third party (ie
            DoorDash), which means

            we may not receive all recipient information for PII purposes.
          nullable: true
    FulfillmentDeliveryDetailsOrderFulfillmentDeliveryDetailsScheduleType:
      type: string
      enum:
        - SCHEDULED
        - ASAP
      x-enum-elements:
        - name: SCHEDULED
          description: Indicates the fulfillment to deliver at a scheduled deliver time.
        - name: ASAP
          description: >-
            Indicates that the fulfillment to deliver as soon as possible and
            should be prepared

            immediately.
      description: The schedule type of the delivery fulfillment.
      x-release-status: BETA
    FulfillmentFulfillmentEntry:
      type: object
      description: >-
        Links an order line item to a fulfillment. Each entry must reference

        a valid `uid` for an order line item in the `line_item_uid` field, as
        well as a `quantity` to

        fulfill.
      x-release-status: BETA
      required:
        - line_item_uid
        - quantity
      properties:
        uid:
          type: string
          description: >-
            A unique ID that identifies the fulfillment entry only within this
            order.
          maxLength: 60
          nullable: true
        line_item_uid:
          type: string
          description: The `uid` from the order line item.
          minLength: 1
        quantity:
          type: string
          description: >-
            The quantity of the line item being fulfilled, formatted as a
            decimal number.

            For example, `"3"`.


            Fulfillments for line items with a `quantity_unit` can have
            non-integer quantities.

            For example, `"1.70000"`.
          minLength: 1
          maxLength: 12
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Application-defined data attached to this fulfillment entry.
            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).
          nullable: true
    FulfillmentFulfillmentLineItemApplication:
      type: string
      enum:
        - ALL
        - ENTRY_LIST
      x-enum-elements:
        - name: ALL
          description: If `ALL`, `entries` must be unset.
        - name: ENTRY_LIST
          description: If `ENTRY_LIST`, supply a list of `entries`.
      description: >-
        The `line_item_application` describes what order line items this
        fulfillment applies

        to. It can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment
        entries.
      x-release-status: BETA
    FulfillmentPickupDetails:
      type: object
      description: Contains details necessary to fulfill a pickup order.
      x-release-status: PUBLIC
      properties:
        recipient:
          $ref: '#/components/schemas/FulfillmentRecipient'
          description: >-
            Information about the person to pick up this fulfillment from a
            physical

            location.
          nullable: true
        expires_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when this fulfillment expires if it is not marked in
            progress. The timestamp must be

            in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z"). The
            expiration time can only be set

            up to 7 days in the future. If `expires_at` is not set, any new
            payments attached to the order

            are automatically completed.
          nullable: true
        auto_complete_duration:
          type: string
          description: >-
            The duration of time after which an in progress pickup fulfillment
            is automatically moved

            to the `COMPLETED` state. The duration must be in RFC 3339 format
            (for example, "P1W3D").


            If not set, this pickup fulfillment remains in progress until it is
            canceled or completed.
          nullable: true
        schedule_type:
          $ref: '#/components/schemas/FulfillmentPickupDetailsScheduleType'
          description: >-
            The schedule type of the pickup fulfillment. Defaults to
            `SCHEDULED`.

            See
            [FulfillmentPickupDetailsScheduleType](#type-fulfillmentpickupdetailsscheduletype)
            for possible values
          nullable: true
        pickup_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            that represents the start of the pickup window. Must be in RFC 3339
            timestamp format, e.g.,

            "2016-09-04T23:59:33.123Z".


            For fulfillments with the schedule type `ASAP`, this is
            automatically set

            to the current time plus the expected duration to prepare the
            fulfillment.
          nullable: true
        pickup_window_duration:
          type: string
          description: >-
            The window of time in which the order should be picked up after the
            `pickup_at` timestamp.

            Must be in RFC 3339 duration format, e.g., "P1W3D". Can be used as
            an

            informational guideline for merchants.
          nullable: true
        prep_time_duration:
          type: string
          description: |-
            The duration of time it takes to prepare this fulfillment.
            The duration must be in RFC 3339 format (for example, "P1W3D").
          nullable: true
        note:
          type: string
          description: >-
            A note to provide additional instructions about the pickup

            fulfillment displayed in the Square Point of Sale application and
            set by the API.
          maxLength: 500
          nullable: true
        placed_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was placed. The timestamp must be in
            RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        accepted_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was marked in progress. The
            timestamp must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        rejected_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was rejected. The timestamp must be
            in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        ready_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment is marked as ready for pickup. The
            timestamp must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        expired_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment expired. The timestamp must be in
            RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        picked_up_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was picked up by the recipient. The
            timestamp must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        canceled_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was canceled. The timestamp must be
            in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        cancel_reason:
          type: string
          description: >-
            A description of why the pickup was canceled. The maximum length:
            100 characters.
          maxLength: 100
          nullable: true
        is_curbside_pickup:
          type: boolean
          description: >-
            If set to `true`, indicates that this pickup order is for curbside
            pickup, not in-store pickup.
          x-release-status: BETA
          nullable: true
        curbside_pickup_details:
          $ref: '#/components/schemas/FulfillmentPickupDetailsCurbsidePickupDetails'
          description: >-
            Specific details for curbside pickup. These details can only be
            populated if `is_curbside_pickup` is set to `true`.
          x-release-status: BETA
          nullable: true
    FulfillmentPickupDetailsCurbsidePickupDetails:
      type: object
      description: Specific details for curbside pickup.
      x-release-status: BETA
      properties:
        curbside_details:
          type: string
          description: >-
            Specific details for curbside pickup, such as parking number and
            vehicle model.
          maxLength: 250
          nullable: true
        buyer_arrived_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the buyer arrived and is waiting for pickup. The
            timestamp must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          nullable: true
    FulfillmentPickupDetailsScheduleType:
      type: string
      enum:
        - SCHEDULED
        - ASAP
      x-enum-elements:
        - name: SCHEDULED
          description: >-
            Indicates that the fulfillment will be picked up at a scheduled
            pickup time.
        - name: ASAP
          description: >-
            Indicates that the fulfillment will be picked up as soon as possible
            and

            should be prepared immediately.
      description: The schedule type of the pickup fulfillment.
      x-release-status: PUBLIC
    FulfillmentRecipient:
      type: object
      description: Information about the fulfillment recipient.
      x-release-status: PUBLIC
      properties:
        customer_id:
          type: string
          description: >-
            The ID of the customer associated with the fulfillment.


            If `customer_id` is provided, the fulfillment recipient's
            `display_name`,

            `email_address`, and `phone_number` are automatically populated from
            the

            targeted customer profile. If these fields are set in the request,
            the request

            values override the information from the customer profile. If the

            targeted customer profile does not contain the necessary information
            and

            these fields are left unset, the request results in an error.
          maxLength: 191
          nullable: true
        display_name:
          type: string
          description: >-
            The display name of the fulfillment recipient. This field is
            required.


            If provided, the display name overrides the corresponding customer
            profile value

            indicated by `customer_id`.
          maxLength: 255
          nullable: true
        email_address:
          type: string
          description: >-
            The email address of the fulfillment recipient.


            If provided, the email address overrides the corresponding customer
            profile value

            indicated by `customer_id`.
          maxLength: 255
          nullable: true
        phone_number:
          type: string
          description: >-
            The phone number of the fulfillment recipient. This field is
            required.


            If provided, the phone number overrides the corresponding customer
            profile value

            indicated by `customer_id`.
          maxLength: 17
          nullable: true
        address:
          $ref: '#/components/schemas/Address'
          description: >-
            The address of the fulfillment recipient. This field is required.


            If provided, the address overrides the corresponding customer
            profile value

            indicated by `customer_id`.
          x-release-status: BETA
          nullable: true
    FulfillmentShipmentDetails:
      type: object
      description: Contains the details necessary to fulfill a shipment order.
      x-release-status: BETA
      properties:
        recipient:
          $ref: '#/components/schemas/FulfillmentRecipient'
          description: Information about the person to receive this shipment fulfillment.
          nullable: true
        carrier:
          type: string
          description: >-
            The shipping carrier being used to ship this fulfillment (such as
            UPS, FedEx, or USPS).
          maxLength: 50
          nullable: true
        shipping_note:
          type: string
          description: A note with additional information for the shipping carrier.
          maxLength: 500
          nullable: true
        shipping_type:
          type: string
          description: >-
            A description of the type of shipping product purchased from the
            carrier

            (such as First Class, Priority, or Express).
          maxLength: 50
          nullable: true
        tracking_number:
          type: string
          description: >-
            The reference number provided by the carrier to track the shipment's
            progress.
          maxLength: 100
          nullable: true
        tracking_url:
          type: string
          description: A link to the tracking webpage on the carrier's website.
          maxLength: 2000
          nullable: true
        placed_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the shipment was requested. The timestamp must be in
            RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        in_progress_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when this fulfillment was moved to the `RESERVED` state,
            which  indicates that preparation

            of this shipment has begun. The timestamp must be in RFC 3339 format
            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        packaged_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when this fulfillment was moved to the `PREPARED` state,
            which indicates that the

            fulfillment is packaged. The timestamp must be in RFC 3339 format
            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        expected_shipped_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the shipment is expected to be delivered to the
            shipping carrier.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          nullable: true
        shipped_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when this fulfillment was moved to the `COMPLETED` state,
            which indicates that

            the fulfillment has been given to the shipping carrier. The
            timestamp must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        canceled_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating the shipment was canceled.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          nullable: true
        cancel_reason:
          type: string
          description: A description of why the shipment was canceled.
          maxLength: 100
          nullable: true
        failed_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the shipment failed to be completed. The timestamp
            must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        failure_reason:
          type: string
          description: A description of why the shipment failed to be completed.
          maxLength: 100
          nullable: true
    FulfillmentState:
      type: string
      enum:
        - PROPOSED
        - RESERVED
        - PREPARED
        - COMPLETED
        - CANCELED
        - FAILED
      x-enum-elements:
        - name: PROPOSED
          description: Indicates that the fulfillment has been proposed.
        - name: RESERVED
          description: Indicates that the fulfillment has been reserved.
        - name: PREPARED
          description: Indicates that the fulfillment has been prepared.
        - name: COMPLETED
          description: Indicates that the fulfillment was successfully completed.
        - name: CANCELED
          description: Indicates that the fulfillment was canceled.
        - name: FAILED
          description: >-
            Indicates that the fulfillment failed to be completed, but was not
            explicitly

            canceled.
      description: The current state of this fulfillment.
      x-release-status: PUBLIC
    FulfillmentType:
      type: string
      enum:
        - PICKUP
        - SHIPMENT
        - DELIVERY
      x-enum-elements:
        - name: PICKUP
          description: >-
            A recipient to pick up the fulfillment from a physical
            [location](entity:Location).
        - name: SHIPMENT
          description: A shipping carrier to ship the fulfillment.
        - name: DELIVERY
          description: A courier to deliver the fulfillment.
      description: The type of fulfillment.
      x-release-status: PUBLIC
    GetBankAccountByV1IdRequest:
      type: object
      description: |-
        Request object for fetching a specific `BankAccount`
        by the object ID.
      x-release-status: PUBLIC
      properties: {}
    GetBankAccountByV1IdResponse:
      type: object
      description: Response object returned by GetBankAccountByV1Id.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        bank_account:
          $ref: '#/components/schemas/BankAccount'
          description: The requested `BankAccount` object.
      example:
        bank_account:
          account_number_suffix: '971'
          account_type: CHECKING
          bank_name: Bank Name
          country: US
          creditable: false
          currency: USD
          debitable: false
          holder_name: Jane Doe
          id: w3yRgCGYQnwmdl0R3GB
          location_id: S8GWD5example
          primary_bank_identification_number: '112200303'
          status: VERIFICATION_IN_PROGRESS
          version: 5
    GetBankAccountRequest:
      type: object
      description: |-
        Request object to fetch a specific `BankAccount`
        by the object ID.
      x-release-status: PUBLIC
      properties: {}
    GetBankAccountResponse:
      type: object
      description: Response object returned by `GetBankAccount`.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        bank_account:
          $ref: '#/components/schemas/BankAccount'
          description: The requested `BankAccount` object.
      example:
        bank_account:
          account_number_suffix: '971'
          account_type: CHECKING
          bank_name: Bank Name
          country: US
          creditable: false
          currency: USD
          debitable: false
          holder_name: Jane Doe
          id: w3yRgCGYQnwmdl0R3GB
          location_id: S8GWD5example
          primary_bank_identification_number: '112200303'
          status: VERIFICATION_IN_PROGRESS
          version: 5
    GetBreakTypeRequest:
      type: object
      description: A request to get a `BreakType` by ID.
      x-release-status: PUBLIC
      properties: {}
    GetBreakTypeResponse:
      type: object
      description: >-
        The response to a request to get a `BreakType`. The response contains

        the requested `BreakType` objects and might contain a set of `Error`
        objects if

        the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        break_type:
          $ref: '#/components/schemas/BreakType'
          description: The response object.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        break_type:
          break_name: Lunch Break
          created_at: '2019-02-21T17:50:00Z'
          expected_duration: PT30M
          id: lA0mj_RSOprNPwMUXdYp
          is_paid: true
          location_id: 059SB0E0WCNWS
          updated_at: '2019-02-21T17:50:00Z'
          version: 1
    GetDeviceCodeRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
      example: {}
    GetDeviceCodeResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        device_code:
          $ref: '#/components/schemas/DeviceCode'
          description: The queried DeviceCode.
      example:
        device_code:
          code: EBCARJ
          created_at: '2020-02-06T18:44:33.000Z'
          device_id: 907CS13101300122
          id: B3Z6NAMYQSMTM
          location_id: B5E4484SHHNYH
          name: Counter 1
          pair_by: '2020-02-06T18:49:33.000Z'
          product_type: TERMINAL_API
          status: PAIRED
          status_changed_at: '2020-02-06T18:47:28.000Z'
    GetDeviceRequest:
      type: object
      x-release-status: BETA
      properties: {}
      example: {}
    GetDeviceResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        device:
          $ref: '#/components/schemas/Device'
          description: The requested `Device`.
      example:
        device:
          attributes:
            manufacturer: Square
            manufacturers_id: 995CS397A6475287
            merchant_token: MLCHXZCBWFGDW
            model: T2
            name: Square Terminal 995
            type: TERMINAL
            updated_at: '2023-09-29T13:12:22.365049321Z'
            version: 5.41.0085
          components:
            - application_details:
                application_type: TERMINAL_API
                session_location: LMN2K7S3RTOU3
                version: '6.25'
              type: APPLICATION
            - card_reader_details:
                version: 3.53.70
              type: CARD_READER
            - battery_details:
                external_power: AVAILABLE_CHARGING
                visible_percent: 5
              type: BATTERY
            - type: WIFI
              wifi_details:
                active: true
                ip_address_v4: 10.0.0.7
                secure_connection: WPA/WPA2 PSK
                signal_strength:
                  value: 2
                ssid: Staff Network
            - ethernet_details:
                active: false
              type: ETHERNET
          id: device:995CS397A6475287
          status:
            category: AVAILABLE
    GetEmployeeWageRequest:
      type: object
      description: A request to get an `EmployeeWage`.
      x-release-status: DEPRECATED
      properties: {}
    GetEmployeeWageResponse:
      type: object
      description: >-
        A response to a request to get an `EmployeeWage`. The response contains

        the requested `EmployeeWage` objects and might contain a set of `Error`
        objects if

        the request resulted in errors.
      x-release-status: DEPRECATED
      properties:
        employee_wage:
          $ref: '#/components/schemas/EmployeeWage'
          description: The requested `EmployeeWage` object.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        employee_wage:
          employee_id: 33fJchumvVdJwxV0H6L9
          hourly_rate:
            amount: 2000
            currency: USD
          id: pXS3qCv7BERPnEGedM4S8mhm
          title: Manager
    GetInvoiceRequest:
      type: object
      description: Describes a `GetInvoice` request.
      x-release-status: PUBLIC
      properties: {}
    GetInvoiceResponse:
      type: object
      description: Describes a `GetInvoice` response.
      x-release-status: PUBLIC
      properties:
        invoice:
          $ref: '#/components/schemas/Invoice'
          description: The invoice requested.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example:
        invoice:
          accepted_payment_methods:
            bank_account: false
            buy_now_pay_later: false
            card: true
            cash_app_pay: false
            square_gift_card: false
          created_at: '2020-06-18T17:45:13Z'
          custom_fields:
            - label: Event Reference Number
              placement: ABOVE_LINE_ITEMS
              value: 'Ref. #1234'
            - label: Terms of Service
              placement: BELOW_LINE_ITEMS
              value: The terms of service are...
          delivery_method: EMAIL
          description: We appreciate your business!
          id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
          invoice_number: inv-100
          location_id: ES0RJRZYEC39A
          order_id: CAISENgvlJ6jLWAzERDzjyHVybY
          payment_requests:
            - automatic_payment_source: NONE
              computed_amount_money:
                amount: 10000
                currency: USD
              due_date: '2030-01-24'
              reminders:
                - message: Your invoice is due tomorrow
                  relative_scheduled_days: -1
                  status: PENDING
                  uid: beebd363-e47f-4075-8785-c235aaa7df11
              request_type: BALANCE
              tipping_enabled: true
              total_completed_amount_money:
                amount: 0
                currency: USD
              uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355
          primary_recipient:
            customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4
            email_address: Amelia.Earhart@example.com
            family_name: Earhart
            given_name: Amelia
            phone_number: 1-212-555-4240
          sale_or_service_date: '2030-01-24'
          scheduled_at: '2030-01-13T10:00:00Z'
          status: DRAFT
          store_payment_method_enabled: false
          timezone: America/Los_Angeles
          title: Event Planning Services
          updated_at: '2020-06-18T17:45:13Z'
          version: 0
    GetPaymentRefundRequest:
      type: object
      description: |-
        Describes a request to retrieve a refund using
        [GetPaymentRefund](api-endpoint:Refunds-GetPaymentRefund).
      x-release-status: PUBLIC
      properties: {}
      example: {}
    GetPaymentRefundResponse:
      type: object
      description: >-
        Defines the response returned by
        [GetRefund](api-endpoint:Refunds-GetPaymentRefund).


        Note: If there are errors processing the request, the refund field might
        not be

        present or it might be present in a FAILED state.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        refund:
          $ref: '#/components/schemas/PaymentRefund'
          description: The requested `PaymentRefund`.
      example:
        refund:
          amount_money:
            amount: 555
            currency: USD
          created_at: '2021-10-13T19:59:05.073Z'
          id: >-
            bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY_69MmgHubkLqx9wGhnmenRUHOaKitE6llfZuxcWYjGxd
          location_id: L88917AVBK2S5
          order_id: 9ltv0bx5PuvGXUYHYHxYSKEqC3IZY
          payment_id: bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY
          processing_fee:
            - amount_money:
                amount: -34
                currency: USD
              effective_at: '2021-10-13T21:34:35.000Z'
              type: INITIAL
          reason: Example Refund
          status: COMPLETED
          updated_at: '2021-10-13T20:00:02.442Z'
    GetPaymentRequest:
      type: object
      description: |-
        Describes a request to retrieve a payment using 
        [GetPayment](api-endpoint:Payments-GetPayment).
      x-release-status: PUBLIC
      properties: {}
      example: {}
    GetPaymentResponse:
      type: object
      description: >-
        Defines the response returned by
        [GetPayment](api-endpoint:Payments-GetPayment).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        payment:
          $ref: '#/components/schemas/Payment'
          description: The requested `Payment`.
      example:
        payment:
          amount_money:
            amount: 555
            currency: USD
          application_details:
            application_id: sq0ids-Pw67AZAlLVB7hsRmwlJPuA
            square_product: VIRTUAL_TERMINAL
          approved_money:
            amount: 555
            currency: USD
          card_details:
            auth_result_code: 2Nkw7q
            avs_status: AVS_ACCEPTED
            card:
              bin: '411111'
              card_brand: VISA
              card_type: DEBIT
              exp_month: 11
              exp_year: 2022
              fingerprint: >-
                sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ
              last_4: '1111'
              prepaid_type: NOT_PREPAID
            card_payment_timeline:
              authorized_at: '2021-10-13T19:34:33.680Z'
              captured_at: '2021-10-13T19:34:34.340Z'
            cvv_status: CVV_ACCEPTED
            entry_method: KEYED
            statement_description: SQ *EXAMPLE TEST GOSQ.C
            status: CAPTURED
          created_at: '2021-10-13T19:34:33.524Z'
          delay_action: CANCEL
          delay_duration: PT168H
          delayed_until: '2021-10-20T19:34:33.524Z'
          employee_id: TMoK_ogh6rH1o4dV
          id: bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY
          location_id: L88917AVBK2S5
          note: Test Note
          order_id: d7eKah653Z579f3gVtjlxpSlmUcZY
          processing_fee:
            - amount_money:
                amount: 34
                currency: USD
              effective_at: '2021-10-13T21:34:35.000Z'
              type: INITIAL
          receipt_number: bP9m
          receipt_url: https://squareup.com/receipt/preview/bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY
          source_type: CARD
          status: COMPLETED
          team_member_id: TMoK_ogh6rH1o4dV
          total_money:
            amount: 555
            currency: USD
          updated_at: '2021-10-13T19:34:34.339Z'
          version_token: 56pRkL3slrzet2iQrTp9n0bdJVYTB9YEWdTNjQfZOPV6o
    GetPayoutRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
      example: {}
    GetPayoutResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        payout:
          $ref: '#/components/schemas/Payout'
          description: The requested payout.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example:
        payout:
          amount_money:
            amount: -103
            currency_code: USD
          arrival_date: '2022-03-24'
          created_at: '2022-03-24T03:07:09Z'
          destination:
            id: bact:ZPp3oedR3AeEUNd3z7
            type: BANK_ACCOUNT
          id: po_f3c0fb38-a5ce-427d-b858-52b925b72e45
          location_id: L88917AVBK2S5
          status: PAID
          type: BATCH
          updated_at: '2022-03-24T03:07:09Z'
          version: 1
    GetShiftRequest:
      type: object
      description: A request to get a `Shift` by ID.
      x-release-status: PUBLIC
      properties: {}
    GetShiftResponse:
      type: object
      description: >-
        A response to a request to get a `Shift`. The response contains

        the requested `Shift` object and might contain a set of `Error` objects
        if

        the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        shift:
          $ref: '#/components/schemas/Shift'
          description: The requested `Shift`.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        shift:
          breaks:
            - break_type_id: 92EPDRQKJ5088
              end_at: '2019-02-23T20:00:00-05:00'
              expected_duration: PT1H
              id: M9BBKEPQAQD2T
              is_paid: true
              name: Lunch Break
              start_at: '2019-02-23T19:00:00-05:00'
          created_at: '2019-02-27T00:12:12Z'
          declared_cash_tip_money:
            amount: 500
            currency: USD
          employee_id: D71KRMQof6cXGUW0aAv7
          end_at: '2019-02-23T21:00:00-05:00'
          id: T35HMQSN89SV4
          location_id: PAA1RJZZKXBFG
          start_at: '2019-02-23T18:00:00-05:00'
          status: CLOSED
          team_member_id: D71KRMQof6cXGUW0aAv7
          timezone: America/New_York
          updated_at: '2019-02-27T00:12:12Z'
          version: 1
          wage:
            hourly_rate:
              amount: 1457
              currency: USD
            job_id: N4YKVLzFj3oGtNocqoYHYpW3
            tip_eligible: true
            title: Cashier
    GetTeamMemberWageRequest:
      type: object
      description: A request to get a `TeamMemberWage`.
      x-release-status: PUBLIC
      properties: {}
    GetTeamMemberWageResponse:
      type: object
      description: >-
        A response to a request to get a `TeamMemberWage`. The response contains

        the requested `TeamMemberWage` objects and might contain a set of
        `Error` objects if

        the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        team_member_wage:
          $ref: '#/components/schemas/TeamMemberWage'
          description: The requested `TeamMemberWage` object.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        team_member_wage:
          hourly_rate:
            amount: 2000
            currency: USD
          id: pXS3qCv7BERPnEGedM4S8mhm
          job_id: jxJNN6eCJsLrhg5UFJrDWDGE
          team_member_id: 33fJchumvVdJwxV0H6L9
          tip_eligible: false
          title: Manager
    GetTerminalActionRequest:
      type: object
      x-release-status: BETA
      properties: {}
      example: {}
    GetTerminalActionResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        action:
          $ref: '#/components/schemas/TerminalAction'
          description: The requested `TerminalAction`
      example:
        action:
          app_id: APP_ID
          created_at: '2021-07-28T23:22:07.476Z'
          deadline_duration: PT5M
          device_id: DEVICE_ID
          id: termapia:jveJIAkkAjILHkdCE
          location_id: LOCATION_ID
          save_card_options:
            customer_id: CUSTOMER_ID
            reference_id: user-id-1
          status: IN_PROGRESS
          type: SAVE_CARD
          updated_at: '2021-07-28T23:22:08.301Z'
    GetTerminalCheckoutRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
      example: {}
    GetTerminalCheckoutResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        checkout:
          $ref: '#/components/schemas/TerminalCheckout'
          description: The requested `TerminalCheckout`.
      example:
        checkout:
          amount_money:
            amount: 2610
            currency: USD
          app_id: APP_ID
          created_at: '2020-04-06T16:39:32.545Z'
          deadline_duration: PT5M
          device_options:
            device_id: dbb5d83a-7838-11ea-bc55-0242ac130003
            skip_receipt_screen: false
            tip_settings:
              allow_tipping: false
          id: 08YceKh7B3ZqO
          location_id: LOCATION_ID
          note: A brief note
          reference_id: id11572
          status: IN_PROGRESS
          updated_at: 2020-04-06T16:39:323.001Z
    GetTerminalRefundRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
      example: {}
    GetTerminalRefundResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        refund:
          $ref: '#/components/schemas/TerminalRefund'
          description: The requested `Refund`.
      example:
        refund:
          amount_money:
            amount: 111
            currency: CAD
          app_id: sandbox-sq0idb-c2OuYt13YaCAeJq_2cd8OQ
          card:
            bin: '411111'
            card_brand: INTERAC
            card_type: CREDIT
            exp_month: 1
            exp_year: 2022
            fingerprint: >-
              sq-1-B1fP9MNNmZgVVaPKRND6oDKYbz25S2cTvg9Mzwg3RMTK1zT1PiGRT-AE3nTA8vSmmw
            last_4: '1111'
          created_at: '2020-09-29T15:21:46.771Z'
          deadline_duration: PT5M
          device_id: f72dfb8e-4d65-4e56-aade-ec3fb8d33291
          id: 009DP5HD-5O5OvgkcNUhl7JBuINflcjKqUzXZY
          location_id: 76C9W6K8CNNQ5
          order_id: kcuKDKreRaI4gF4TjmEgZjHk8Z7YY
          payment_id: 5O5OvgkcNUhl7JBuINflcjKqUzXZY
          reason: Returning item
          refund_id: >-
            5O5OvgkcNUhl7JBuINflcjKqUzXZY_43Q4iGp7sNeATiWrUruA1EYeMRUXaddXXlDDJ1EQLvb
          status: COMPLETED
          updated_at: '2020-09-29T15:21:48.675Z'
    GiftCard:
      type: object
      description: Represents a Square gift card.
      x-release-status: PUBLIC
      required:
        - type
      properties:
        id:
          type: string
          description: The Square-assigned ID of the gift card.
          readOnly: true
        type:
          $ref: '#/components/schemas/GiftCardType'
          description: |-
            The gift card type.
            See [Type](#type-type) for possible values
        gan_source:
          $ref: '#/components/schemas/GiftCardGANSource'
          description: >-
            The source that generated the gift card account number (GAN). The
            default value is `SQUARE`.

            See [GANSource](#type-gansource) for possible values
          nullable: true
        state:
          $ref: '#/components/schemas/GiftCardStatus'
          description: |-
            The current gift card state.
            See [Status](#type-status) for possible values
          readOnly: true
        balance_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The current gift card balance. This balance is always greater than
            or equal to zero.
          readOnly: true
        gan:
          type: string
          description: >-
            The gift card account number (GAN). Buyers can use the GAN to make
            purchases or check 

            the gift card balance.
          nullable: true
        created_at:
          type: string
          description: >-
            The timestamp when the gift card was created, in RFC 3339 format. 

            In the case of a digital gift card, it is the time when you create a
            card 

            (using the Square Point of Sale application, Seller Dashboard, or
            Gift Cards API).  

            In the case of a plastic gift card, it is the time when Square
            associates the card with the 

            seller at the time of activation.
          readOnly: true
        customer_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of the [customer profiles](entity:Customer) to whom this
            gift card is linked.
          readOnly: true
    GiftCardActivity:
      type: object
      description: >-
        Represents an action performed on a [gift card](entity:GiftCard) that
        affects its state or balance. 

        A gift card activity contains information about a specific activity
        type. For example, a `REDEEM` activity

        includes a `redeem_activity_details` field that contains information
        about the redemption.
      x-release-status: PUBLIC
      required:
        - type
        - location_id
      properties:
        id:
          type: string
          description: The Square-assigned ID of the gift card activity.
          readOnly: true
        type:
          $ref: '#/components/schemas/GiftCardActivityType'
          description: |-
            The type of gift card activity.
            See [Type](#type-type) for possible values
        location_id:
          type: string
          description: >-
            The ID of the [business location](entity:Location) where the
            activity occurred.
        created_at:
          type: string
          description: >-
            The timestamp when the gift card activity was created, in RFC 3339
            format.
          readOnly: true
        gift_card_id:
          type: string
          description: >-
            The gift card ID. When creating a gift card activity, `gift_card_id`
            is not required if 

            `gift_card_gan` is specified.
          nullable: true
        gift_card_gan:
          type: string
          description: >-
            The gift card account number (GAN). When creating a gift card
            activity, `gift_card_gan` 

            is not required if `gift_card_id` is specified.
          nullable: true
        gift_card_balance_money:
          $ref: '#/components/schemas/Money'
          description: The final balance on the gift card after the action is completed.
          readOnly: true
        load_activity_details:
          $ref: '#/components/schemas/GiftCardActivityLoad'
          description: >-
            Additional details about a `LOAD` activity, which is used to reload
            money onto a gift card.
          nullable: true
        activate_activity_details:
          $ref: '#/components/schemas/GiftCardActivityActivate'
          description: >-
            Additional details about an `ACTIVATE` activity, which is used to
            activate a gift card with 

            an initial balance.
          nullable: true
        redeem_activity_details:
          $ref: '#/components/schemas/GiftCardActivityRedeem'
          description: >-
            Additional details about a `REDEEM` activity, which is used to
            redeem a gift card for a purchase.


            For applications that process payments using the Square Payments
            API, Square creates a `REDEEM` activity that 

            updates the gift card balance after the corresponding
            [CreatePayment](api-endpoint:Payments-CreatePayment) 

            request is completed. Applications that use a custom payment
            processing system must call 

            [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity)
            to create the `REDEEM` activity.
          nullable: true
        clear_balance_activity_details:
          $ref: '#/components/schemas/GiftCardActivityClearBalance'
          description: >-
            Additional details about a `CLEAR_BALANCE` activity, which is used
            to set the balance of a gift card to zero.
          nullable: true
        deactivate_activity_details:
          $ref: '#/components/schemas/GiftCardActivityDeactivate'
          description: >-
            Additional details about a `DEACTIVATE` activity, which is used to
            deactivate a gift card.
          nullable: true
        adjust_increment_activity_details:
          $ref: '#/components/schemas/GiftCardActivityAdjustIncrement'
          description: >-
            Additional details about an `ADJUST_INCREMENT` activity, which is
            used to add money to a gift card 

            outside of a typical `ACTIVATE`, `LOAD`, or `REFUND` activity flow.
          nullable: true
        adjust_decrement_activity_details:
          $ref: '#/components/schemas/GiftCardActivityAdjustDecrement'
          description: >-
            Additional details about an `ADJUST_DECREMENT` activity, which is
            used to deduct money from a gift 

            card outside of a typical `REDEEM` activity flow.
          nullable: true
        refund_activity_details:
          $ref: '#/components/schemas/GiftCardActivityRefund'
          description: >-
            Additional details about a `REFUND` activity, which is used to add
            money to a gift card when 

            refunding a payment.


            For applications that refund payments to a gift card using the
            Square Refunds API, Square automatically

            creates a `REFUND` activity that updates the gift card balance after
            a [RefundPayment](api-endpoint:Refunds-RefundPayment)

            request is completed. Applications that use a custom processing
            system must call

            [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity)
            to create the `REFUND` activity.
          nullable: true
        unlinked_activity_refund_activity_details:
          $ref: '#/components/schemas/GiftCardActivityUnlinkedActivityRefund'
          description: >-
            Additional details about an `UNLINKED_ACTIVITY_REFUND` activity.
            This activity is used to add money 

            to a gift card when refunding a payment that was processed using a
            custom payment processing system

            and not linked to the gift card.
          nullable: true
        import_activity_details:
          $ref: '#/components/schemas/GiftCardActivityImport'
          description: >-
            Additional details about an `IMPORT` activity, which Square uses to
            import a third-party 

            gift card with a balance.
          readOnly: true
        block_activity_details:
          $ref: '#/components/schemas/GiftCardActivityBlock'
          description: >-
            Additional details about a `BLOCK` activity, which Square uses to
            temporarily block a gift card.
          readOnly: true
        unblock_activity_details:
          $ref: '#/components/schemas/GiftCardActivityUnblock'
          description: >-
            Additional details about an `UNBLOCK` activity, which Square uses to
            unblock a gift card.
          readOnly: true
        import_reversal_activity_details:
          $ref: '#/components/schemas/GiftCardActivityImportReversal'
          description: >-
            Additional details about an `IMPORT_REVERSAL` activity, which Square
            uses to reverse the 

            import of a third-party gift card.
          readOnly: true
        transfer_balance_to_activity_details:
          $ref: '#/components/schemas/GiftCardActivityTransferBalanceTo'
          description: >-
            Additional details about a `TRANSFER_BALANCE_TO` activity, which
            Square uses to add money to

            a gift card as the result of a transfer from another gift card.
          readOnly: true
        transfer_balance_from_activity_details:
          $ref: '#/components/schemas/GiftCardActivityTransferBalanceFrom'
          description: >-
            Additional details about a `TRANSFER_BALANCE_FROM` activity, which
            Square uses to deduct money from

            a gift as the result of a transfer to another gift card.
          readOnly: true
    GiftCardActivityActivate:
      type: object
      description: >-
        Represents details about an `ACTIVATE` [gift card activity
        type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      properties:
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount added to the gift card. This value is a positive integer.


            Applications that use a custom order processing system must specify
            this amount in the 

            [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity)
            request.
          nullable: true
        order_id:
          type: string
          description: >-
            The ID of the [order](entity:Order) that contains the `GIFT_CARD`
            line item.


            Applications that use the Square Orders API to process orders must
            specify the order ID

            [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity)
            request.
          nullable: true
        line_item_uid:
          type: string
          description: >-
            The UID of the `GIFT_CARD` line item in the order that represents
            the gift card purchase.


            Applications that use the Square Orders API to process orders must
            specify the line item UID

            in the
            [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity)
            request.
          nullable: true
        reference_id:
          type: string
          description: >-
            A client-specified ID that associates the gift card activity with an
            entity in another system. 


            Applications that use a custom order processing system can use this
            field to track information 

            related to an order or payment.
          nullable: true
        buyer_payment_instrument_ids:
          type: array
          items:
            type: string
          description: >-
            The payment instrument IDs used to process the gift card purchase,
            such as a credit card ID 

            or bank account ID. 


            Applications that use a custom order processing system must specify
            payment instrument IDs in 

            the
            [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity)
            request.

            Square uses this information to perform compliance checks. 


            For applications that use the Square Orders API to process payments,
            Square has the necessary 

            instrument IDs to perform compliance checks.


            Each buyer payment instrument ID can contain a maximum of 255
            characters.
          nullable: true
    GiftCardActivityAdjustDecrement:
      type: object
      description: >-
        Represents details about an `ADJUST_DECREMENT` [gift card activity
        type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      required:
        - amount_money
        - reason
      properties:
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount deducted from the gift card balance. This value is a
            positive integer.
        reason:
          $ref: '#/components/schemas/GiftCardActivityAdjustDecrementReason'
          description: |-
            The reason the gift card balance was adjusted.
            See [Reason](#type-reason) for possible values
    GiftCardActivityAdjustDecrementReason:
      type: string
      enum:
        - SUSPICIOUS_ACTIVITY
        - BALANCE_ACCIDENTALLY_INCREASED
        - SUPPORT_ISSUE
        - PURCHASE_WAS_REFUNDED
      x-enum-elements:
        - name: SUSPICIOUS_ACTIVITY
          description: >-
            The balance was decreased because the seller detected suspicious or
            fraudulent activity

            on the gift card.
        - name: BALANCE_ACCIDENTALLY_INCREASED
          description: >-
            The balance was decreased to reverse an unintentional balance
            increase.
        - name: SUPPORT_ISSUE
          description: The balance was decreased to accommodate support issues.
        - name: PURCHASE_WAS_REFUNDED
          description: >-
            The balance was decreased because the order used to purchase or
            reload the

            gift card was refunded.
      description: >-
        Indicates the reason for deducting money from a [gift
        card](entity:GiftCard).
      x-release-status: PUBLIC
    GiftCardActivityAdjustIncrement:
      type: object
      description: >-
        Represents details about an `ADJUST_INCREMENT` [gift card activity
        type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      required:
        - amount_money
        - reason
      properties:
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount added to the gift card balance. This value is a positive
            integer.
        reason:
          $ref: '#/components/schemas/GiftCardActivityAdjustIncrementReason'
          description: |-
            The reason the gift card balance was adjusted.
            See [Reason](#type-reason) for possible values
    GiftCardActivityAdjustIncrementReason:
      type: string
      enum:
        - COMPLIMENTARY
        - SUPPORT_ISSUE
        - TRANSACTION_VOIDED
      x-enum-elements:
        - name: COMPLIMENTARY
          description: The seller gifted a complimentary gift card balance increase.
        - name: SUPPORT_ISSUE
          description: |-
            The seller increased the gift card balance 
            to accommodate support issues.
        - name: TRANSACTION_VOIDED
          description: The transaction is voided.
      description: Indicates the reason for adding money to a [gift card](entity:GiftCard).
      x-release-status: PUBLIC
    GiftCardActivityBlock:
      type: object
      description: >-
        Represents details about a `BLOCK` [gift card activity
        type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      required:
        - reason
      properties:
        reason:
          $ref: '#/components/schemas/GiftCardActivityBlockReason'
          description: |-
            The reason the gift card was blocked.
            See [Reason](#type-reason) for possible values
    GiftCardActivityBlockReason:
      type: string
      enum:
        - CHARGEBACK_BLOCK
      x-enum-elements:
        - name: CHARGEBACK_BLOCK
          description: >-
            The gift card is blocked because the buyer initiated a chargeback on
            the gift card purchase.
      description: Indicates the reason for blocking a [gift card](entity:GiftCard).
      x-release-status: PUBLIC
    GiftCardActivityClearBalance:
      type: object
      description: >-
        Represents details about a `CLEAR_BALANCE` [gift card activity
        type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      required:
        - reason
      properties:
        reason:
          $ref: '#/components/schemas/GiftCardActivityClearBalanceReason'
          description: |-
            The reason the gift card balance was cleared.
            See [Reason](#type-reason) for possible values
    GiftCardActivityClearBalanceReason:
      type: string
      enum:
        - SUSPICIOUS_ACTIVITY
        - REUSE_GIFTCARD
        - UNKNOWN_REASON
      x-enum-elements:
        - name: SUSPICIOUS_ACTIVITY
          description: The seller suspects suspicious activity.
        - name: REUSE_GIFTCARD
          description: The seller cleared the balance to reuse the gift card.
        - name: UNKNOWN_REASON
          description: >-
            The gift card balance was cleared for an unknown reason.


            This reason is read-only and cannot be used to create a
            `CLEAR_BALANCE` activity using the Gift Card Activities API.
      description: >-
        Indicates the reason for clearing the balance of a [gift
        card](entity:GiftCard).
      x-release-status: PUBLIC
    GiftCardActivityDeactivate:
      type: object
      description: >-
        Represents details about a `DEACTIVATE` [gift card activity
        type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      required:
        - reason
      properties:
        reason:
          $ref: '#/components/schemas/GiftCardActivityDeactivateReason'
          description: |-
            The reason the gift card was deactivated.
            See [Reason](#type-reason) for possible values
    GiftCardActivityDeactivateReason:
      type: string
      enum:
        - SUSPICIOUS_ACTIVITY
        - UNKNOWN_REASON
        - CHARGEBACK_DEACTIVATE
      x-enum-elements:
        - name: SUSPICIOUS_ACTIVITY
          description: The seller suspects suspicious activity.
        - name: UNKNOWN_REASON
          description: >-
            The gift card was deactivated for an unknown reason.


            This reason is read-only and cannot be used to create a `DEACTIVATE`
            activity using the Gift Card Activities API.
        - name: CHARGEBACK_DEACTIVATE
          description: >-
            A chargeback on the gift card purchase (or the gift card load) was
            ruled in favor of the buyer.


            This reason is read-only and cannot be used to create a `DEACTIVATE`
            activity using the Gift Card Activities API.
      description: Indicates the reason for deactivating a [gift card](entity:GiftCard).
      x-release-status: PUBLIC
    GiftCardActivityImport:
      type: object
      description: >-
        Represents details about an `IMPORT` [gift card activity
        type](entity:GiftCardActivityType).

        This activity type is used when Square imports a third-party gift card,
        in which case the 

        `gan_source` of the gift card is set to `OTHER`.
      x-release-status: PUBLIC
      required:
        - amount_money
      properties:
        amount_money:
          $ref: '#/components/schemas/Money'
          description: The balance amount on the imported gift card.
    GiftCardActivityImportReversal:
      type: object
      description: >-
        Represents details about an `IMPORT_REVERSAL` [gift card activity
        type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      required:
        - amount_money
      properties:
        amount_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The amount of money cleared from the third-party gift card when 
            the import was reversed.
    GiftCardActivityLoad:
      type: object
      description: >-
        Represents details about a `LOAD` [gift card activity
        type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      properties:
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount added to the gift card. This value is a positive integer.


            Applications that use a custom order processing system must specify
            this amount in the 

            [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity)
            request.
          nullable: true
        order_id:
          type: string
          description: >-
            The ID of the [order](entity:Order) that contains the `GIFT_CARD`
            line item.


            Applications that use the Square Orders API to process orders must
            specify the order ID in the 

            [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity)
            request.
          nullable: true
        line_item_uid:
          type: string
          description: >-
            The UID of the `GIFT_CARD` line item in the order that represents
            the additional funds for the gift card.


            Applications that use the Square Orders API to process orders must
            specify the line item UID

            in the
            [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity)
            request.
          nullable: true
        reference_id:
          type: string
          description: >-
            A client-specified ID that associates the gift card activity with an
            entity in another system. 


            Applications that use a custom order processing system can use this
            field to track information related to 

            an order or payment.
          nullable: true
        buyer_payment_instrument_ids:
          type: array
          items:
            type: string
          description: >-
            The payment instrument IDs used to process the order for the
            additional funds, such as a credit card ID 

            or bank account ID. 


            Applications that use a custom order processing system must specify
            payment instrument IDs in 

            the
            [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity)
            request.

            Square uses this information to perform compliance checks. 


            For applications that use the Square Orders API to process payments,
            Square has the necessary 

            instrument IDs to perform compliance checks.


            Each buyer payment instrument ID can contain a maximum of 255
            characters.
          nullable: true
    GiftCardActivityRedeem:
      type: object
      description: >-
        Represents details about a `REDEEM` [gift card activity
        type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      required:
        - amount_money
      properties:
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount deducted from the gift card for the redemption. This
            value is a positive integer.


            Applications that use a custom payment processing system must
            specify this amount in the 

            [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity)
            request.
        payment_id:
          type: string
          description: >-
            The ID of the payment that represents the gift card redemption.
            Square populates this field 

            if the payment was processed by Square.
          readOnly: true
        reference_id:
          type: string
          description: >-
            A client-specified ID that associates the gift card activity with an
            entity in another system. 


            Applications that use a custom payment processing system can use
            this field to track information

            related to an order or payment.
          nullable: true
        status:
          $ref: '#/components/schemas/GiftCardActivityRedeemStatus'
          description: >-
            The status of the gift card redemption. Gift cards redeemed from
            Square Point of Sale or the 

            Square Seller Dashboard use a two-state process: `PENDING` 

            to `COMPLETED` or `PENDING` to  `CANCELED`. Gift cards redeemed
            using the Gift Card Activities API 

            always have a `COMPLETED` status.

            See [Status](#type-status) for possible values
          readOnly: true
    GiftCardActivityRedeemStatus:
      type: string
      enum:
        - PENDING
        - COMPLETED
        - CANCELED
      x-enum-elements:
        - name: PENDING
          description: >-
            The gift card redemption is pending. `PENDING` is a temporary status
            that applies when a 

            gift card is redeemed from Square Point of Sale or another Square
            product. A `PENDING` status is updated to 

            `COMPLETED` if the payment is captured or `CANCELED` if the
            authorization is voided.
        - name: COMPLETED
          description: The gift card redemption is completed.
        - name: CANCELED
          description: >-
            The gift card redemption is canceled. A redemption is canceled if
            the authorization 

            on the gift card is voided.
      description: >-
        Indicates the status of a [gift card](entity:GiftCard) redemption. This
        status is relevant only for

        redemptions made from Square products (such as Square Point of Sale)
        because Square products use a 

        two-state process. Gift cards redeemed using the Gift Card Activities
        API always have a `COMPLETED` status.
      x-release-status: PUBLIC
    GiftCardActivityRefund:
      type: object
      description: >-
        Represents details about a `REFUND` [gift card activity
        type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      properties:
        redeem_activity_id:
          type: string
          description: >-
            The ID of the refunded `REDEEM` gift card activity. Square populates
            this field if the 

            `payment_id` in the corresponding
            [RefundPayment](api-endpoint:Refunds-RefundPayment) request 

            represents a gift card redemption.


            For applications that use a custom payment processing system, this
            field is required when creating

            a `REFUND` activity. The provided `REDEEM` activity ID must be
            linked to the same gift card.
          nullable: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount added to the gift card for the refund. This value is a
            positive integer.


            This field is required when creating a `REFUND` activity. The amount
            can represent a full or partial refund.
          nullable: true
        reference_id:
          type: string
          description: >-
            A client-specified ID that associates the gift card activity with an
            entity in another system.
          nullable: true
        payment_id:
          type: string
          description: >-
            The ID of the refunded payment. Square populates this field if the
            refund is for a 

            payment processed by Square. This field matches the `payment_id` in
            the corresponding

            [RefundPayment](api-endpoint:Refunds-RefundPayment) request.
          readOnly: true
    GiftCardActivityTransferBalanceFrom:
      type: object
      description: >-
        Represents details about a `TRANSFER_BALANCE_FROM` [gift card activity
        type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      required:
        - transfer_to_gift_card_id
        - amount_money
      properties:
        transfer_to_gift_card_id:
          type: string
          description: >-
            The ID of the gift card to which the specified amount was
            transferred.
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount deducted from the gift card for the transfer. This value
            is a positive integer.
    GiftCardActivityTransferBalanceTo:
      type: object
      description: >-
        Represents details about a `TRANSFER_BALANCE_TO` [gift card activity
        type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      required:
        - transfer_from_gift_card_id
        - amount_money
      properties:
        transfer_from_gift_card_id:
          type: string
          description: >-
            The ID of the gift card from which the specified amount was
            transferred.
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount added to the gift card balance for the transfer. This
            value is a positive integer.
    GiftCardActivityType:
      type: string
      enum:
        - ACTIVATE
        - LOAD
        - REDEEM
        - CLEAR_BALANCE
        - DEACTIVATE
        - ADJUST_INCREMENT
        - ADJUST_DECREMENT
        - REFUND
        - UNLINKED_ACTIVITY_REFUND
        - IMPORT
        - BLOCK
        - UNBLOCK
        - IMPORT_REVERSAL
        - TRANSFER_BALANCE_FROM
        - TRANSFER_BALANCE_TO
      x-enum-elements:
        - name: ACTIVATE
          description: >-
            Activated a gift card with a balance. When a gift card is activated,
            Square changes 

            the gift card state from `PENDING` to `ACTIVE`. A gift card must be
            in the `ACTIVE` state 

            to be used for other balance-changing activities.
        - name: LOAD
          description: Loaded a gift card with additional funds.
        - name: REDEEM
          description: Redeemed a gift card for a purchase.
        - name: CLEAR_BALANCE
          description: Set the balance of a gift card to zero.
        - name: DEACTIVATE
          description: Permanently blocked a gift card from balance-changing activities.
        - name: ADJUST_INCREMENT
          description: >-
            Added money to a gift card outside of a typical `ACTIVATE`, `LOAD`,
            or `REFUND` activity flow.
        - name: ADJUST_DECREMENT
          description: >-
            Deducted money from a gift card outside of a typical `REDEEM`
            activity flow.
        - name: REFUND
          description: >-
            Added money to a gift card from a refunded transaction. A `REFUND`
            activity might be linked to 

            a Square payment, depending on how the payment and refund are
            processed. For example:

            - A payment processed by Square can be refunded to a `PENDING` or
            `ACTIVE` gift card using the Square

            Seller Dashboard, Square Point of Sale, or Refunds API.

            - A payment processed using a custom processing system can be
            refunded to the same gift card.
        - name: UNLINKED_ACTIVITY_REFUND
          description: >-
            Added money to a gift card from a refunded transaction that was
            processed using a custom payment

            processing system and not linked to the gift card.
        - name: IMPORT
          description: >-
            Imported a third-party gift card with a balance. `IMPORT` activities
            are managed 

            by Square and cannot be created using the Gift Card Activities API.
        - name: BLOCK
          description: >-
            Temporarily blocked a gift card from balance-changing activities.
            `BLOCK` activities 

            are managed by Square and cannot be created using the Gift Card
            Activities API.
        - name: UNBLOCK
          description: >-
            Unblocked a gift card, which enables it to resume balance-changing
            activities. `UNBLOCK` 

            activities are managed by Square and cannot be created using the
            Gift Card Activities API.
        - name: IMPORT_REVERSAL
          description: >-
            Reversed the import of a third-party gift card, which sets the gift
            card state to 

            `PENDING` and clears the balance. `IMPORT_REVERSAL` activities are
            managed by Square and 

            cannot be created using the Gift Card Activities API.
        - name: TRANSFER_BALANCE_FROM
          description: >-
            Deducted money from a gift card as the result of a transfer to the
            balance of another gift card.

            `TRANSFER_BALANCE_FROM` activities are managed by Square and cannot
            be created using the Gift Card Activities API.
        - name: TRANSFER_BALANCE_TO
          description: >-
            Added money to a gift card as the result of a transfer from the
            balance of another gift card.

            `TRANSFER_BALANCE_TO` activities are managed by Square and cannot be
            created using the Gift Card Activities API.
      description: Indicates the type of [gift card activity](entity:GiftCardActivity).
      x-release-status: PUBLIC
    GiftCardActivityUnblock:
      type: object
      description: >-
        Represents details about an `UNBLOCK` [gift card activity
        type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      required:
        - reason
      properties:
        reason:
          $ref: '#/components/schemas/GiftCardActivityUnblockReason'
          description: |-
            The reason the gift card was unblocked.
            See [Reason](#type-reason) for possible values
    GiftCardActivityUnblockReason:
      type: string
      enum:
        - CHARGEBACK_UNBLOCK
      x-enum-elements:
        - name: CHARGEBACK_UNBLOCK
          description: >-
            The gift card is unblocked because a chargeback was ruled in favor
            of the seller.
      description: Indicates the reason for unblocking a [gift card](entity:GiftCard).
      x-release-status: PUBLIC
    GiftCardActivityUnlinkedActivityRefund:
      type: object
      description: >-
        Represents details about an `UNLINKED_ACTIVITY_REFUND` [gift card
        activity type](entity:GiftCardActivityType).
      x-release-status: PUBLIC
      required:
        - amount_money
      properties:
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount added to the gift card for the refund. This value is a
            positive integer.
        reference_id:
          type: string
          description: >-
            A client-specified ID that associates the gift card activity with an
            entity in another system.
          nullable: true
        payment_id:
          type: string
          description: >-
            The ID of the refunded payment. This field is not used starting in
            Square version 2022-06-16.
          readOnly: true
    GiftCardGANSource:
      type: string
      enum:
        - SQUARE
        - OTHER
      x-enum-elements:
        - name: SQUARE
          description: The GAN is generated by Square.
        - name: OTHER
          description: >-
            The GAN is provided by a non-Square system. For more information,
            see 

            [Custom
            GANs](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api#custom-gans)
            or 

            [Third-party gift
            cards](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api#third-party-gift-cards).
      description: |-
        Indicates the source that generated the gift card 
        account number (GAN).
      x-release-status: PUBLIC
    GiftCardStatus:
      type: string
      enum:
        - ACTIVE
        - DEACTIVATED
        - BLOCKED
        - PENDING
      x-enum-elements:
        - name: ACTIVE
          description: The gift card is active and can be used as a payment source.
        - name: DEACTIVATED
          description: >-
            Any activity that changes the gift card balance is permanently
            forbidden.
        - name: BLOCKED
          description: >-
            Any activity that changes the gift card balance is temporarily
            forbidden.
        - name: PENDING
          description: >-
            The gift card is pending activation.

            This is the initial state when a gift card is created. Typically,
            you'll call

            [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity)
            to create an

            `ACTIVATE` activity that activates the gift card with an initial
            balance before first use.
      description: Indicates the gift card state.
      x-release-status: PUBLIC
    GiftCardType:
      type: string
      enum:
        - PHYSICAL
        - DIGITAL
      x-enum-elements:
        - name: PHYSICAL
          description: A plastic gift card.
        - name: DIGITAL
          description: A digital gift card.
      description: Indicates the gift card type.
      x-release-status: PUBLIC
    InventoryAdjustment:
      type: object
      description: |-
        Represents a change in state or quantity of product inventory at a
        particular time and location.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: |-
            A unique ID generated by Square for the
            `InventoryAdjustment`.
          maxLength: 100
        reference_id:
          type: string
          description: |-
            An optional ID provided by the application to tie the
            `InventoryAdjustment` to an external
            system.
          maxLength: 255
          nullable: true
        from_state:
          $ref: '#/components/schemas/InventoryState'
          description: |-
            The [inventory state](entity:InventoryState) of the related quantity
            of items before the adjustment.
            See [InventoryState](#type-inventorystate) for possible values
          nullable: true
        to_state:
          $ref: '#/components/schemas/InventoryState'
          description: |-
            The [inventory state](entity:InventoryState) of the related quantity
            of items after the adjustment.
            See [InventoryState](#type-inventorystate) for possible values
          nullable: true
        location_id:
          type: string
          description: >-
            The Square-generated ID of the [Location](entity:Location) where the
            related

            quantity of items is being tracked.
          maxLength: 100
          nullable: true
        catalog_object_id:
          type: string
          description: |-
            The Square-generated ID of the
            [CatalogObject](entity:CatalogObject) being tracked.
          maxLength: 100
          nullable: true
        catalog_object_type:
          type: string
          description: >-
            The [type](entity:CatalogObjectType) of the
            [CatalogObject](entity:CatalogObject) being tracked. 


            The Inventory API supports setting and reading the
            `"catalog_object_type": "ITEM_VARIATION"` field value. 

            In addition, it can also read the `"catalog_object_type": "ITEM"`
            field value that is set by the Square Restaurants app.
          maxLength: 14
          nullable: true
        quantity:
          type: string
          description: |-
            The number of items affected by the adjustment as a decimal string.
            Can support up to 5 digits after the decimal point.
          maxLength: 26
          nullable: true
        total_price_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The total price paid for goods associated with the
            adjustment. Present if and only if `to_state` is `SOLD`. Always
            non-negative.
          readOnly: true
        occurred_at:
          type: string
          description: >-
            A client-generated RFC 3339-formatted timestamp that indicates when

            the inventory adjustment took place. For inventory adjustment
            updates, the `occurred_at`

            timestamp cannot be older than 24 hours or in the future relative to
            the

            time of the request.
          maxLength: 34
          nullable: true
        created_at:
          type: string
          description: >-
            An RFC 3339-formatted timestamp that indicates when the inventory
            adjustment is received.
          maxLength: 34
          readOnly: true
        source:
          $ref: '#/components/schemas/SourceApplication'
          description: |-
            Information about the application that caused the
            inventory adjustment.
          readOnly: true
        employee_id:
          type: string
          description: >-
            The Square-generated ID of the [Employee](entity:Employee)
            responsible for the

            inventory adjustment.
          maxLength: 100
          nullable: true
        team_member_id:
          type: string
          description: >-
            The Square-generated ID of the [Team Member](entity:TeamMember)
            responsible for the

            inventory adjustment.
          maxLength: 100
          nullable: true
        transaction_id:
          type: string
          description: >-
            The Square-generated ID of the [Transaction](entity:Transaction)
            that

            caused the adjustment. Only relevant for payment-related state

            transitions.
          maxLength: 255
          readOnly: true
        refund_id:
          type: string
          description: |-
            The Square-generated ID of the [Refund](entity:Refund) that
            caused the adjustment. Only relevant for refund-related state
            transitions.
          maxLength: 255
          readOnly: true
        purchase_order_id:
          type: string
          description: >-
            The Square-generated ID of the purchase order that caused the

            adjustment. Only relevant for state transitions from the Square for
            Retail

            app.
          maxLength: 100
          readOnly: true
        goods_receipt_id:
          type: string
          description: >-
            The Square-generated ID of the goods receipt that caused the

            adjustment. Only relevant for state transitions from the Square for
            Retail

            app.
          maxLength: 100
          readOnly: true
        adjustment_group:
          $ref: '#/components/schemas/InventoryAdjustmentGroup'
          description: >-
            An adjustment group bundling the related adjustments of item
            variations through stock conversions in a single inventory event.
          readOnly: true
          x-release-status: BETA
    InventoryAdjustmentGroup:
      type: object
      x-release-status: BETA
      properties:
        id:
          type: string
          description: |-
            A unique ID generated by Square for the
            `InventoryAdjustmentGroup`.
          maxLength: 100
          readOnly: true
        root_adjustment_id:
          type: string
          description: The inventory adjustment of the composed variation.
          maxLength: 100
          readOnly: true
        from_state:
          $ref: '#/components/schemas/InventoryState'
          description: >-
            Representative `from_state` for adjustments within the group. For
            example, for a group adjustment from `IN_STOCK` to `SOLD`,

            there can be two component adjustments in the group: one from
            `IN_STOCK`to `COMPOSED` and the other one from `COMPOSED` to `SOLD`.

            Here, the representative `from_state` for the
            `InventoryAdjustmentGroup` is `IN_STOCK`.

            See [InventoryState](#type-inventorystate) for possible values
          readOnly: true
        to_state:
          $ref: '#/components/schemas/InventoryState'
          description: >-
            Representative `to_state` for adjustments within group. For example,
            for a group adjustment from `IN_STOCK` to `SOLD`,

            the two component adjustments in the group can be from `IN_STOCK` to
            `COMPOSED` and from `COMPOSED` to `SOLD`.

            Here, the representative `to_state` of the
            `InventoryAdjustmentGroup` is `SOLD`.

            See [InventoryState](#type-inventorystate) for possible values
          readOnly: true
    InventoryAlertType:
      type: string
      enum:
        - NONE
        - LOW_QUANTITY
      x-enum-elements:
        - name: NONE
          description: The variation does not display an alert.
        - name: LOW_QUANTITY
          description: The variation generates an alert when its quantity is low.
      description: >-
        Indicates whether Square should alert the merchant when the inventory
        quantity of a CatalogItemVariation is low.
      x-release-status: PUBLIC
    InventoryChange:
      type: object
      description: |-
        Represents a single physical count, inventory, adjustment, or transfer
        that is part of the history of inventory changes for a particular
        [CatalogObject](entity:CatalogObject) instance.
      x-release-status: PUBLIC
      properties:
        type:
          $ref: '#/components/schemas/InventoryChangeType'
          description: >-
            Indicates how the inventory change is applied. See

            [InventoryChangeType](entity:InventoryChangeType) for all possible
            values.

            See [InventoryChangeType](#type-inventorychangetype) for possible
            values
          nullable: true
        physical_count:
          $ref: '#/components/schemas/InventoryPhysicalCount'
          description: |-
            Contains details about the physical count when `type` is
            `PHYSICAL_COUNT`, and is unset for all other change types.
          nullable: true
        adjustment:
          $ref: '#/components/schemas/InventoryAdjustment'
          description: |-
            Contains details about the inventory adjustment when `type` is
            `ADJUSTMENT`, and is unset for all other change types.
          nullable: true
        transfer:
          $ref: '#/components/schemas/InventoryTransfer'
          description: >-
            Contains details about the inventory transfer when `type` is

            `TRANSFER`, and is unset for all other change types.


            _Note:_ An [InventoryTransfer](entity:InventoryTransfer) object can
            only be set in the input to the

            [BatchChangeInventory](api-endpoint:Inventory-BatchChangeInventory)
            endpoint when the seller has an active Retail Plus subscription.
          nullable: true
        measurement_unit:
          $ref: '#/components/schemas/CatalogMeasurementUnit'
          description: >-
            The [CatalogMeasurementUnit](entity:CatalogMeasurementUnit) object
            representing the catalog measurement unit associated with the
            inventory change.
          readOnly: true
        measurement_unit_id:
          type: string
          description: >-
            The ID of the
            [CatalogMeasurementUnit](entity:CatalogMeasurementUnit) object
            representing the catalog measurement unit associated with the
            inventory change.
          readOnly: true
    InventoryChangeType:
      type: string
      enum:
        - PHYSICAL_COUNT
        - ADJUSTMENT
        - TRANSFER
      x-enum-elements:
        - name: PHYSICAL_COUNT
          description: The change occurred as part of a physical count update.
        - name: ADJUSTMENT
          description: |-
            The change occurred as part of the normal lifecycle of goods
            (e.g., as an inventory adjustment).
        - name: TRANSFER
          description: The change occurred as part of an inventory transfer.
      description: >-
        Indicates how the inventory change was applied to a tracked product
        quantity.
      x-release-status: PUBLIC
    InventoryCount:
      type: object
      description: >-
        Represents Square-estimated quantity of items in a particular state at a

        particular seller location based on the known history of physical counts
        and

        inventory adjustments.
      x-release-status: PUBLIC
      properties:
        catalog_object_id:
          type: string
          description: |-
            The Square-generated ID of the
            [CatalogObject](entity:CatalogObject) being tracked.
          maxLength: 100
          nullable: true
        catalog_object_type:
          type: string
          description: >-
            The [type](entity:CatalogObjectType) of the
            [CatalogObject](entity:CatalogObject) being tracked. 


            The Inventory API supports setting and reading the
            `"catalog_object_type": "ITEM_VARIATION"` field value. 

            In addition, it can also read the `"catalog_object_type": "ITEM"`
            field value that is set by the Square Restaurants app.
          maxLength: 14
          nullable: true
        state:
          $ref: '#/components/schemas/InventoryState'
          description: |-
            The current [inventory state](entity:InventoryState) for the related
            quantity of items.
            See [InventoryState](#type-inventorystate) for possible values
          nullable: true
        location_id:
          type: string
          description: >-
            The Square-generated ID of the [Location](entity:Location) where the
            related

            quantity of items is being tracked.
          maxLength: 100
          nullable: true
        quantity:
          type: string
          description: >-
            The number of items affected by the estimated count as a decimal
            string.

            Can support up to 5 digits after the decimal point.
          maxLength: 26
          nullable: true
        calculated_at:
          type: string
          description: >-
            An RFC 3339-formatted timestamp that indicates when the most recent
            physical count or adjustment affecting

            the estimated count is received.
          maxLength: 34
          readOnly: true
        is_estimated:
          type: boolean
          description: >-
            Whether the inventory count is for composed variation (TRUE) or not
            (FALSE). If true, the inventory count will not be present in the
            response of

            any of these endpoints:
            [BatchChangeInventory](api-endpoint:Inventory-BatchChangeInventory),

            [BatchRetrieveInventoryChanges](api-endpoint:Inventory-BatchRetrieveInventoryChanges),

            [BatchRetrieveInventoryCounts](api-endpoint:Inventory-BatchRetrieveInventoryCounts),
            and

            [RetrieveInventoryChanges](api-endpoint:Inventory-RetrieveInventoryChanges).
          readOnly: true
          x-release-status: BETA
    InventoryPhysicalCount:
      type: object
      description: >-
        Represents the quantity of an item variation that is physically present

        at a specific location, verified by a seller or a seller's employee. For
        example,

        a physical count might come from an employee counting the item
        variations on

        hand or from syncing with an external system.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: |-
            A unique Square-generated ID for the
            [InventoryPhysicalCount](entity:InventoryPhysicalCount).
          maxLength: 100
        reference_id:
          type: string
          description: >-
            An optional ID provided by the application to tie the

            [InventoryPhysicalCount](entity:InventoryPhysicalCount) to an
            external

            system.
          maxLength: 255
          nullable: true
        catalog_object_id:
          type: string
          description: |-
            The Square-generated ID of the
            [CatalogObject](entity:CatalogObject) being tracked.
          maxLength: 100
          nullable: true
        catalog_object_type:
          type: string
          description: >-
            The [type](entity:CatalogObjectType) of the
            [CatalogObject](entity:CatalogObject) being tracked. 


            The Inventory API supports setting and reading the
            `"catalog_object_type": "ITEM_VARIATION"` field value. 

            In addition, it can also read the `"catalog_object_type": "ITEM"`
            field value that is set by the Square Restaurants app.
          maxLength: 14
          nullable: true
        state:
          $ref: '#/components/schemas/InventoryState'
          description: |-
            The current [inventory state](entity:InventoryState) for the related
            quantity of items.
            See [InventoryState](#type-inventorystate) for possible values
          nullable: true
        location_id:
          type: string
          description: >-
            The Square-generated ID of the [Location](entity:Location) where the
            related

            quantity of items is being tracked.
          maxLength: 100
          nullable: true
        quantity:
          type: string
          description: >-
            The number of items affected by the physical count as a decimal
            string.

            The number can support up to 5 digits after the decimal point.
          maxLength: 26
          nullable: true
        source:
          $ref: '#/components/schemas/SourceApplication'
          description: |-
            Information about the application with which the
            physical count is submitted.
          readOnly: true
        employee_id:
          type: string
          description: >-
            The Square-generated ID of the [Employee](entity:Employee)
            responsible for the

            physical count.
          maxLength: 100
          nullable: true
        team_member_id:
          type: string
          description: >-
            The Square-generated ID of the [Team Member](entity:TeamMember)
            responsible for the

            physical count.
          maxLength: 100
          nullable: true
        occurred_at:
          type: string
          description: >-
            A client-generated RFC 3339-formatted timestamp that indicates when

            the physical count was examined. For physical count updates, the
            `occurred_at`

            timestamp cannot be older than 24 hours or in the future relative to
            the

            time of the request.
          maxLength: 34
          nullable: true
        created_at:
          type: string
          description: >-
            An RFC 3339-formatted timestamp that indicates when the physical
            count is received.
          maxLength: 34
          readOnly: true
    InventoryState:
      type: string
      enum:
        - CUSTOM
        - IN_STOCK
        - SOLD
        - RETURNED_BY_CUSTOMER
        - RESERVED_FOR_SALE
        - SOLD_ONLINE
        - ORDERED_FROM_VENDOR
        - RECEIVED_FROM_VENDOR
        - IN_TRANSIT_TO
        - NONE
        - WASTE
        - UNLINKED_RETURN
        - COMPOSED
        - DECOMPOSED
        - SUPPORTED_BY_NEWER_VERSION
        - IN_TRANSIT
      x-enum-elements:
        - name: CUSTOM
          description: |-
            The related quantity of items are in a custom state. **READ-ONLY**:
            the Inventory API cannot move quantities to or from this state.
        - name: IN_STOCK
          description: The related quantity of items are on hand and available for sale.
        - name: SOLD
          description: |-
            The related quantity of items were sold as part of an itemized
            transaction. Quantities in the `SOLD` state are no longer tracked.
        - name: RETURNED_BY_CUSTOMER
          description: >-
            The related quantity of items were returned through the Square Point

            of Sale application, but are not yet available for sale.
            **READ-ONLY**:

            the Inventory API cannot move quantities to or from this state.
        - name: RESERVED_FOR_SALE
          description: |-
            The related quantity of items are on hand, but not currently
            available for sale. **READ-ONLY**: the Inventory API cannot move
            quantities to or from this state.
        - name: SOLD_ONLINE
          description: |-
            The related quantity of items were sold online. **READ-ONLY**: the
            Inventory API cannot move quantities to or from this state.
        - name: ORDERED_FROM_VENDOR
          description: >-
            The related quantity of items were ordered from a vendor but not yet

            received. **READ-ONLY**: the Inventory API cannot move quantities to
            or

            from this state.
        - name: RECEIVED_FROM_VENDOR
          description: >-
            The related quantity of items were received from a vendor but are

            not yet available for sale. **READ-ONLY**: the Inventory API cannot
            move

            quantities to or from this state.
        - name: IN_TRANSIT_TO
          description: |-
            Replaced by `IN_TRANSIT` to represent quantities
            of items that are in transit between locations.
        - name: NONE
          description: >-
            A placeholder indicating that the related quantity of items are not

            currently tracked in Square. Transferring quantities from the `NONE`
            state

            to a tracked state (e.g., `IN_STOCK`) introduces stock into the
            system.
        - name: WASTE
          description: |-
            The related quantity of items are lost or damaged and cannot be
            sold.
        - name: UNLINKED_RETURN
          description: >-
            The related quantity of items were returned but not linked to a

            previous transaction. Unlinked returns are not tracked in Square.

            Transferring a quantity from `UNLINKED_RETURN` to a tracked state
            (e.g.,

            `IN_STOCK`) introduces new stock into the system.
        - name: COMPOSED
          description: >-
            The related quantity of items that are part of a composition
            consisting one or more components.
        - name: DECOMPOSED
          description: The related quantity of items that are part of a component.
        - name: SUPPORTED_BY_NEWER_VERSION
          description: >-
            This state is not supported by this version of the Square API. We
            recommend that you upgrade the client to use the appropriate version
            of the Square API supporting this state.
        - name: IN_TRANSIT
          description: >-
            The related quantity of items are in transit between locations.
            **READ-ONLY:** the Inventory API cannot currently be used to move
            quantities to or from this inventory state.
      description: >-
        Indicates the state of a tracked item quantity in the lifecycle of
        goods.
      x-release-status: PUBLIC
    InventoryTransfer:
      type: object
      description: |-
        Represents the transfer of a quantity of product inventory at a
        particular time from one location to another.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: |-
            A unique ID generated by Square for the
            `InventoryTransfer`.
          maxLength: 100
        reference_id:
          type: string
          description: |-
            An optional ID provided by the application to tie the
            `InventoryTransfer` to an external system.
          maxLength: 255
          nullable: true
        state:
          $ref: '#/components/schemas/InventoryState'
          description: |-
            The [inventory state](entity:InventoryState) for the quantity of
            items being transferred.
            See [InventoryState](#type-inventorystate) for possible values
          nullable: true
        from_location_id:
          type: string
          description: >-
            The Square-generated ID of the [Location](entity:Location) where the
            related

            quantity of items was tracked before the transfer.
          maxLength: 100
          nullable: true
        to_location_id:
          type: string
          description: >-
            The Square-generated ID of the [Location](entity:Location) where the
            related

            quantity of items was tracked after the transfer.
          maxLength: 100
          nullable: true
        catalog_object_id:
          type: string
          description: |-
            The Square-generated ID of the
            [CatalogObject](entity:CatalogObject) being tracked.
          maxLength: 100
          nullable: true
        catalog_object_type:
          type: string
          description: >-
            The [type](entity:CatalogObjectType) of the
            [CatalogObject](entity:CatalogObject) being tracked. 


            The Inventory API supports setting and reading the
            `"catalog_object_type": "ITEM_VARIATION"` field value. 

            In addition, it can also read the `"catalog_object_type": "ITEM"`
            field value that is set by the Square Restaurants app.
          maxLength: 14
          nullable: true
        quantity:
          type: string
          description: |-
            The number of items affected by the transfer as a decimal string.
            Can support up to 5 digits after the decimal point.
          maxLength: 26
          nullable: true
        occurred_at:
          type: string
          description: >-
            A client-generated RFC 3339-formatted timestamp that indicates when

            the transfer took place. For write actions, the `occurred_at`
            timestamp

            cannot be older than 24 hours or in the future relative to the time
            of the

            request.
          maxLength: 34
          nullable: true
        created_at:
          type: string
          description: |-
            An RFC 3339-formatted timestamp that indicates when Square
            received the transfer request.
          maxLength: 34
          readOnly: true
        source:
          $ref: '#/components/schemas/SourceApplication'
          description: |-
            Information about the application that initiated the
            inventory transfer.
          readOnly: true
        employee_id:
          type: string
          description: >-
            The Square-generated ID of the [Employee](entity:Employee)
            responsible for the

            inventory transfer.
          maxLength: 100
          nullable: true
        team_member_id:
          type: string
          description: >-
            The Square-generated ID of the [Team Member](entity:TeamMember)
            responsible for the

            inventory transfer.
          maxLength: 100
          nullable: true
    Invoice:
      type: object
      description: >-
        Stores information about an invoice. You use the Invoices API to create
        and manage

        invoices. For more information, see [Invoices API
        Overview](https://developer.squareup.com/docs/invoices-api/overview).
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: The Square-assigned ID of the invoice.
          readOnly: true
        version:
          type: integer
          description: >-
            The Square-assigned version number, which is incremented each time
            an update is committed to the invoice.
        location_id:
          type: string
          description: >-
            The ID of the location that this invoice is associated with. 


            If specified in a `CreateInvoice` request, the value must match the
            `location_id` of the associated order.
          minLength: 1
          maxLength: 255
          nullable: true
        order_id:
          type: string
          description: >-
            The ID of the [order](entity:Order) for which the invoice is
            created. 

            This field is required when creating an invoice, and the order must
            be in the `OPEN` state.


            To view the line items and other information for the associated
            order, call the 

            [RetrieveOrder](api-endpoint:Orders-RetrieveOrder) endpoint using
            the order ID.
          minLength: 1
          maxLength: 255
          nullable: true
        primary_recipient:
          $ref: '#/components/schemas/InvoiceRecipient'
          description: >-
            The customer who receives the invoice. This customer data is
            displayed on the invoice and used by Square to deliver the invoice. 


            This field is required to publish an invoice, and it must specify
            the `customer_id`.
          nullable: true
        payment_requests:
          type: array
          items:
            $ref: '#/components/schemas/InvoicePaymentRequest'
          description: >-
            The payment schedule for the invoice, represented by one or more
            payment requests that

            define payment settings, such as amount due and due date. An invoice
            supports the following payment request combinations:

            - One balance

            - One deposit with one balance

            - 212 installments 

            - One deposit with 212 installments


            This field is required when creating an invoice. It must contain at
            least one payment request. 

            All payment requests for the invoice must equal the total order
            amount. For more information, see 

            [Configuring payment
            requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests).


            Adding `INSTALLMENT` payment requests to an invoice requires an 

            [Invoices Plus
            subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).
          nullable: true
        delivery_method:
          $ref: '#/components/schemas/InvoiceDeliveryMethod'
          description: >-
            The delivery method that Square uses to send the invoice, reminders,
            and receipts to

            the customer. After the invoice is published, Square processes the
            invoice based on the delivery

            method and payment request settings, either immediately or on the
            `scheduled_at` date, if specified.

            For example, Square might send the invoice or receipt for an
            automatic payment. For invoices with

            automatic payments, this field must be set to `EMAIL`.


            One of the following is required when creating an invoice:

            - (Recommended) This `delivery_method` field. To configure an
            automatic payment, the

            `automatic_payment_source` field of the payment request is also
            required.

            - The deprecated `request_method` field of the payment request. Note
            that `invoice`

            objects returned in responses do not include `request_method`.

            See [InvoiceDeliveryMethod](#type-invoicedeliverymethod) for
            possible values
          nullable: true
        invoice_number:
          type: string
          description: >-
            A user-friendly invoice number that is displayed on the invoice. The
            value is unique within a location.

            If not provided when creating an invoice, Square assigns a value.

            It increments from 1 and is padded with zeros making it 7 characters
            long

            (for example, 0000001 and 0000002).
          minLength: 1
          maxLength: 191
          nullable: true
        title:
          type: string
          description: The title of the invoice, which is displayed on the invoice.
          minLength: 1
          maxLength: 255
          nullable: true
        description:
          type: string
          description: The description of the invoice, which is displayed on the invoice.
          minLength: 1
          maxLength: 65536
          nullable: true
        scheduled_at:
          type: string
          description: >-
            The timestamp when the invoice is scheduled for processing, in RFC
            3339 format.

            After the invoice is published, Square processes the invoice on the
            specified date,

            according to the delivery method and payment request settings.


            If the field is not set, Square processes the invoice immediately
            after it is published.
          nullable: true
        public_url:
          type: string
          description: >-
            The URL of the Square-hosted invoice page.

            After you publish the invoice using the `PublishInvoice` endpoint,
            Square hosts the invoice

            page and returns the page URL in the response.
          readOnly: true
        next_payment_amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The current amount due for the invoice. In addition to the

            amount due on the next payment request, this includes any overdue
            payment amounts.
          readOnly: true
        status:
          $ref: '#/components/schemas/InvoiceStatus'
          description: |-
            The status of the invoice.
            See [InvoiceStatus](#type-invoicestatus) for possible values
          readOnly: true
        timezone:
          type: string
          description: >-
            The time zone used to interpret calendar dates on the invoice, such
            as `due_date`.

            When an invoice is created, this field is set to the `timezone`
            specified for the seller

            location. The value cannot be changed.


            For example, a payment `due_date` of 2021-03-09 with a `timezone` of
            America/Los\_Angeles

            becomes overdue at midnight on March 9 in America/Los\_Angeles
            (which equals a UTC timestamp

            of 2021-03-10T08:00:00Z).
          readOnly: true
        created_at:
          type: string
          description: The timestamp when the invoice was created, in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: The timestamp when the invoice was last updated, in RFC 3339 format.
          readOnly: true
        accepted_payment_methods:
          $ref: '#/components/schemas/InvoiceAcceptedPaymentMethods'
          description: >-
            The payment methods that customers can use to pay the invoice on the
            Square-hosted

            invoice page. This setting is independent of any automatic payment
            requests for the invoice.


            This field is required when creating an invoice and must set at
            least one payment method to `true`.
          nullable: true
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceCustomField'
          description: >-
            Additional seller-defined fields that are displayed on the invoice.
            For more information, see

            [Custom
            fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields).


            Adding custom fields to an invoice requires an 

            [Invoices Plus
            subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).


            Max: 2 custom fields
          nullable: true
        subscription_id:
          type: string
          description: >-
            The ID of the [subscription](entity:Subscription) associated with
            the invoice.

            This field is present only on subscription billing invoices.
          readOnly: true
        sale_or_service_date:
          type: string
          description: >-
            The date of the sale or the date that the service is rendered, in
            `YYYY-MM-DD` format.

            This field can be used to specify a past or future date which is
            displayed on the invoice.
          nullable: true
        payment_conditions:
          type: string
          description: >-
            **France only.** The payment terms and conditions that are displayed
            on the invoice. For more information, 

            see [Payment
            conditions](https://developer.squareup.com/docs/invoices-api/overview#payment-conditions).


            For countries other than France, Square returns an
            `INVALID_REQUEST_ERROR` with a `BAD_REQUEST` code and 

            "Payment conditions are not supported for this location's country"
            detail if this field is included in `CreateInvoice` or
            `UpdateInvoice` requests.
          minLength: 1
          maxLength: 2000
          nullable: true
        store_payment_method_enabled:
          type: boolean
          description: >-
            Indicates whether to allow a customer to save a credit or debit card
            as a card on file or a bank transfer as a

            bank account on file. If `true`, Square displays a __Save my card on
            file__ or __Save my bank on file__ checkbox on the

            invoice payment page. Stored payment information can be used for
            future automatic payments. The default value is `false`.
          nullable: true
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceAttachment'
          description: >-
            Metadata about the attachments on the invoice. Invoice attachments
            are managed using the

            [CreateInvoiceAttachment](api-endpoint:Invoices-CreateInvoiceAttachment)
            and
            [DeleteInvoiceAttachment](api-endpoint:Invoices-DeleteInvoiceAttachment)
            endpoints.
          readOnly: true
    InvoiceAcceptedPaymentMethods:
      type: object
      description: >-
        The payment methods that customers can use to pay an
        [invoice](entity:Invoice) on the Square-hosted invoice payment page.
      x-release-status: PUBLIC
      properties:
        card:
          type: boolean
          description: >-
            Indicates whether credit card or debit card payments are accepted.
            The default value is `false`.
          nullable: true
        square_gift_card:
          type: boolean
          description: >-
            Indicates whether Square gift card payments are accepted. The
            default value is `false`.
          nullable: true
        bank_account:
          type: boolean
          description: >-
            Indicates whether ACH bank transfer payments are accepted. The
            default value is `false`.
          nullable: true
        buy_now_pay_later:
          type: boolean
          description: >-
            Indicates whether Afterpay (also known as Clearpay) payments are
            accepted. The default value is `false`.


            This option is allowed only for invoices that have a single payment
            request of the `BALANCE` type. This payment method is

            supported if the seller account accepts Afterpay payments and the
            seller location is in a country where Afterpay

            invoice payments are supported. As a best practice, consider
            enabling an additional payment method when allowing

            `buy_now_pay_later` payments. For more information, including
            detailed requirements and processing limits, see

            [Buy Now Pay Later payments with
            Afterpay](https://developer.squareup.com/docs/invoices-api/overview#buy-now-pay-later).
          nullable: true
        cash_app_pay:
          type: boolean
          description: >-
            Indicates whether Cash App payments are accepted. The default value
            is `false`.


            This payment method is supported only for seller
            [locations](entity:Location) in the United States.
          nullable: true
    InvoiceAttachment:
      type: object
      description: Represents a file attached to an [invoice](entity:Invoice).
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: The Square-assigned ID of the attachment.
          readOnly: true
        filename:
          type: string
          description: The file name of the attachment, which is displayed on the invoice.
          readOnly: true
        description:
          type: string
          description: >-
            The description of the attachment, which is displayed on the
            invoice.

            This field maps to the seller-defined **Message** field.
          readOnly: true
        filesize:
          type: integer
          description: The file size of the attachment in bytes.
          readOnly: true
        hash:
          type: string
          description: The MD5 hash that was generated from the file contents.
          readOnly: true
        mime_type:
          type: string
          description: >-
            The mime type of the attachment.

            The following mime types are supported: 

            image/gif, image/jpeg, image/png, image/tiff, image/bmp,
            application/pdf.
          readOnly: true
        uploaded_at:
          type: string
          description: The timestamp when the attachment was uploaded, in RFC 3339 format.
          readOnly: true
    InvoiceAutomaticPaymentSource:
      type: string
      enum:
        - NONE
        - CARD_ON_FILE
        - BANK_ON_FILE
      x-enum-elements:
        - name: NONE
          description: An automatic payment is not configured for the payment request.
        - name: CARD_ON_FILE
          description: >-
            Use a card on file as the automatic payment method. On the due date,
            Square charges the card

            for the amount of the payment request.


            For `CARD_ON_FILE` payments, the invoice delivery method must be
            `EMAIL` and `card_id` must be

            specified for the payment request before the invoice can be
            published.
        - name: BANK_ON_FILE
          description: >-
            Use a bank account on file as the automatic payment method. On the
            due date, Square charges the bank

            account for the amount of the payment request if the buyer has
            approved the payment. The buyer receives a

            request to approve the payment when the invoice is sent or the
            invoice is updated.


            This payment method applies only to invoices that sellers create in
            the Seller Dashboard or other

            Square product. The bank account is provided by the customer during
            the payment flow. 


            You cannot set `BANK_ON_FILE` as a payment method using the Invoices
            API, but you can change a `BANK_ON_FILE`

            payment method to `NONE` or `CARD_ON_FILE`. For `BANK_ON_FILE`
            payments, the invoice delivery method must be `EMAIL`.
      description: >-
        Indicates the automatic payment method for an [invoice payment
        request](entity:InvoicePaymentRequest).
      x-release-status: PUBLIC
    InvoiceCustomField:
      type: object
      description: >-
        An additional seller-defined and customer-facing field to include on the
        invoice. For more information, 

        see [Custom
        fields](https://developer.squareup.com/docs/invoices-api/overview#custom-fields).


        Adding custom fields to an invoice requires an 

        [Invoices Plus
        subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).
      x-release-status: PUBLIC
      properties:
        label:
          type: string
          description: >-
            The label or title of the custom field. This field is required for a
            custom field.
          maxLength: 30
          nullable: true
        value:
          type: string
          description: >-
            The text of the custom field. If omitted, only the label is
            rendered.
          maxLength: 2000
          nullable: true
        placement:
          $ref: '#/components/schemas/InvoiceCustomFieldPlacement'
          description: >-
            The location of the custom field on the invoice. This field is
            required for a custom field.

            See [InvoiceCustomFieldPlacement](#type-invoicecustomfieldplacement)
            for possible values
          nullable: true
    InvoiceCustomFieldPlacement:
      type: string
      enum:
        - ABOVE_LINE_ITEMS
        - BELOW_LINE_ITEMS
      x-enum-elements:
        - name: ABOVE_LINE_ITEMS
          description: Render the custom field above the invoice line items.
        - name: BELOW_LINE_ITEMS
          description: Render the custom field below the invoice line items.
      description: >-
        Indicates where to render a custom field on the Square-hosted invoice
        page and in emailed or PDF 

        copies of the invoice.
      x-release-status: PUBLIC
    InvoiceDeliveryMethod:
      type: string
      enum:
        - EMAIL
        - SHARE_MANUALLY
        - SMS
      x-enum-elements:
        - name: EMAIL
          description: >-
            Directs Square to send invoices, reminders, and receipts to the
            customer using email.
        - name: SHARE_MANUALLY
          description: >-
            Directs Square to take no action on the invoice. In this case, the
            seller

            or application developer follows up with the customer for payment.
            For example,

            a seller might collect a payment in the Seller Dashboard or Point of
            Sale (POS) application.

            The seller might also share the URL of the Square-hosted invoice
            page (`public_url`) with the customer to request payment.
        - name: SMS
          description: >-
            Directs Square to send invoices and receipts to the customer using
            SMS (text message).


            You cannot set `SMS` as a delivery method using the Invoices API,
            but you can change an `SMS` delivery method to `EMAIL` or
            `SHARE_MANUALLY`.
      description: >-
        Indicates how Square delivers the [invoice](entity:Invoice) to the
        customer.
      x-release-status: PUBLIC
    InvoiceFilter:
      type: object
      description: Describes query filters to apply.
      x-release-status: PUBLIC
      required:
        - location_ids
      properties:
        location_ids:
          type: array
          items:
            type: string
          description: >-
            Limits the search to the specified locations. A location is
            required. 

            In the current implementation, only one location can be specified.
        customer_ids:
          type: array
          items:
            type: string
          description: >-
            Limits the search to the specified customers, within the specified
            locations. 

            Specifying a customer is optional. In the current implementation, 

            a maximum of one customer can be specified.
          nullable: true
    InvoicePaymentReminder:
      type: object
      description: >-
        Describes a payment request reminder (automatic notification) that
        Square sends

        to the customer. You configure a reminder relative to the payment
        request

        `due_date`.
      x-release-status: PUBLIC
      properties:
        uid:
          type: string
          description: >-
            A Square-assigned ID that uniquely identifies the reminder within
            the

            `InvoicePaymentRequest`.
          readOnly: true
        relative_scheduled_days:
          type: integer
          description: >-
            The number of days before (a negative number) or after (a positive
            number)

            the payment request `due_date` when the reminder is sent. For
            example, -3 indicates that

            the reminder should be sent 3 days before the payment request
            `due_date`.
          minimum: -32767
          maximum: 32767
          nullable: true
        message:
          type: string
          description: The reminder message.
          minLength: 1
          maxLength: 1000
          nullable: true
        status:
          $ref: '#/components/schemas/InvoicePaymentReminderStatus'
          description: >-
            The status of the reminder.

            See
            [InvoicePaymentReminderStatus](#type-invoicepaymentreminderstatus)
            for possible values
          readOnly: true
        sent_at:
          type: string
          description: >-
            If sent, the timestamp when the reminder was sent, in RFC 3339
            format.
          readOnly: true
    InvoicePaymentReminderStatus:
      type: string
      enum:
        - PENDING
        - NOT_APPLICABLE
        - SENT
      x-enum-elements:
        - name: PENDING
          description: >-
            The reminder will be sent on the `relative_scheduled_date` (if the
            invoice is published).
        - name: NOT_APPLICABLE
          description: >-
            The reminder is not applicable and is not sent. The following are
            examples

            of when reminders are not applicable and are not sent:

            - You schedule a reminder to be sent before the invoice is
            published.

            - The invoice is configured with multiple payment requests and a
            payment request reminder

            is configured to be sent after the next payment request `due_date`.

            - Two reminders (for different payment requests) are configured to
            be sent on the

            same date. Therefore, only one reminder is sent.

            - You configure a reminder to be sent on the date that the invoice
            is scheduled to be sent.

            - The payment request is already paid.

            - The invoice status is `CANCELED` or `FAILED`.
        - name: SENT
          description: The reminder is sent.
      description: The status of a payment request reminder.
      x-release-status: PUBLIC
    InvoicePaymentRequest:
      type: object
      description: >-
        Represents a payment request for an [invoice](entity:Invoice). Invoices
        can specify a maximum

        of 13 payment requests, with up to 12 `INSTALLMENT` request types. For
        more information, 

        see [Configuring payment
        requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests).


        Adding `INSTALLMENT` payment requests to an invoice requires an 

        [Invoices Plus
        subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).
      x-release-status: PUBLIC
      properties:
        uid:
          type: string
          description: >-
            The Square-generated ID of the payment request in an
            [invoice](entity:Invoice).
          minLength: 1
          maxLength: 255
          nullable: true
        request_method:
          $ref: '#/components/schemas/InvoiceRequestMethod'
          description: >-
            Indicates how Square processes the payment request. DEPRECATED at
            version 2021-01-21. Replaced by the

            `Invoice.delivery_method` and
            `InvoicePaymentRequest.automatic_payment_source` fields.


            One of the following is required when creating an invoice:

            - (Recommended) The `delivery_method` field of the invoice. To
            configure an automatic payment, the

            `automatic_payment_source` field of the payment request is also
            required.

            - This `request_method` field. Note that `invoice` objects returned
            in responses do not include `request_method`.

            See [InvoiceRequestMethod](#type-invoicerequestmethod) for possible
            values
          x-release-status: DEPRECATED
          nullable: true
        request_type:
          $ref: '#/components/schemas/InvoiceRequestType'
          description: >-
            Identifies the payment request type. This type defines how the
            payment request amount is determined. 

            This field is required to create a payment request.

            See [InvoiceRequestType](#type-invoicerequesttype) for possible
            values
          nullable: true
        due_date:
          type: string
          description: >-
            The due date (in the invoice's time zone) for the payment request,
            in `YYYY-MM-DD` format. This field

            is required to create a payment request. If an
            `automatic_payment_source` is defined for the request, Square

            charges the payment source on this date.


            After this date, the invoice becomes overdue. For example, a payment
            `due_date` of 2021-03-09 with a `timezone`

            of America/Los\_Angeles becomes overdue at midnight on March 9 in
            America/Los\_Angeles (which equals a UTC

            timestamp of 2021-03-10T08:00:00Z).
          nullable: true
        fixed_amount_requested_money:
          $ref: '#/components/schemas/Money'
          description: >-
            If the payment request specifies `DEPOSIT` or `INSTALLMENT` as the
            `request_type`, 

            this indicates the request amount.

            You cannot specify this when `request_type` is `BALANCE` or when
            the 

            payment request includes the `percentage_requested` field.
          nullable: true
        percentage_requested:
          type: string
          description: >-
            Specifies the amount for the payment request in percentage:


            - When the payment `request_type` is `DEPOSIT`, it is the percentage
            of the order's total amount.

            - When the payment `request_type` is `INSTALLMENT`, it is the
            percentage of the order's total less 

            the deposit, if requested. The sum of the `percentage_requested` in
            all installment 

            payment requests must be equal to 100.


            You cannot specify this when the payment `request_type` is `BALANCE`
            or when the 

            payment request specifies the `fixed_amount_requested_money` field.
          nullable: true
        tipping_enabled:
          type: boolean
          description: >-
            If set to true, the Square-hosted invoice page (the `public_url`
            field of the invoice) 

            provides a place for the customer to pay a tip. 


            This field is allowed only on the final payment request  

            and the payment `request_type` must be `BALANCE` or `INSTALLMENT`.
          nullable: true
        automatic_payment_source:
          $ref: '#/components/schemas/InvoiceAutomaticPaymentSource'
          description: >-
            The payment method for an automatic payment.


            The default value is `NONE`.

            See
            [InvoiceAutomaticPaymentSource](#type-invoiceautomaticpaymentsource)
            for possible values
          nullable: true
        card_id:
          type: string
          description: >-
            The ID of the credit or debit card on file to charge for the payment
            request. To get the cards on file for a customer,

            call [ListCards](api-endpoint:Cards-ListCards) and include the
            `customer_id` of the invoice recipient.
          minLength: 1
          maxLength: 255
          nullable: true
        reminders:
          type: array
          items:
            $ref: '#/components/schemas/InvoicePaymentReminder'
          description: A list of one or more reminders to send for the payment request.
          nullable: true
        computed_amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of the payment request, computed using the order amount
            and information from the various payment

            request fields (`request_type`, `fixed_amount_requested_money`, and
            `percentage_requested`).
          readOnly: true
        total_completed_amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money already paid for the specific payment request. 

            This amount might include a rounding adjustment if the most recent
            invoice payment 

            was in cash in a currency that rounds cash payments (such as, `CAD`
            or `AUD`).
          readOnly: true
        rounding_adjustment_included_money:
          $ref: '#/components/schemas/Money'
          description: >-
            If the most recent payment was a cash payment 

            in a currency that rounds cash payments (such as, `CAD` or `AUD`)
            and the payment 

            is rounded from `computed_amount_money` in the payment request, then
            this 

            field specifies the rounding adjustment applied. This amount 

            might be negative.
          readOnly: true
    InvoiceQuery:
      type: object
      description: Describes query criteria for searching invoices.
      x-release-status: PUBLIC
      required:
        - filter
      properties:
        filter:
          $ref: '#/components/schemas/InvoiceFilter'
          description: >-
            Query filters to apply in searching invoices. 

            For more information, see [Search for
            invoices](https://developer.squareup.com/docs/invoices-api/retrieve-list-search-invoices#search-invoices).
        sort:
          $ref: '#/components/schemas/InvoiceSort'
          description: Describes the sort order for the search result.
          nullable: true
    InvoiceRecipient:
      type: object
      description: >-
        Represents a snapshot of customer data. This object stores customer data
        that is displayed on the invoice 

        and that Square uses to deliver the invoice.


        When you provide a customer ID for a draft invoice, Square retrieves the
        associated customer profile and populates 

        the remaining `InvoiceRecipient` fields. You cannot update these fields
        after the invoice is published. 

        Square updates the customer ID in response to a merge operation, but
        does not update other fields.
      x-release-status: PUBLIC
      properties:
        customer_id:
          type: string
          description: |-
            The ID of the customer. This is the customer profile ID that 
            you provide when creating a draft invoice.
          minLength: 1
          maxLength: 255
          nullable: true
        given_name:
          type: string
          description: The recipient's given (that is, first) name.
          readOnly: true
        family_name:
          type: string
          description: The recipient's family (that is, last) name.
          readOnly: true
        email_address:
          type: string
          description: The recipient's email address.
          readOnly: true
        address:
          $ref: '#/components/schemas/Address'
          description: The recipient's physical address.
          readOnly: true
        phone_number:
          type: string
          description: The recipient's phone number.
          readOnly: true
        company_name:
          type: string
          description: The name of the recipient's company.
          readOnly: true
        tax_ids:
          $ref: '#/components/schemas/InvoiceRecipientTaxIds'
          description: >-
            The recipient's tax IDs. The country of the seller account
            determines whether this field 

            is available for the customer. For more information, see [Invoice
            recipient tax
            IDs](https://developer.squareup.com/docs/invoices-api/overview#recipient-tax-ids).
          readOnly: true
    InvoiceRecipientTaxIds:
      type: object
      description: >-
        Represents the tax IDs for an invoice recipient. The country of the
        seller account determines 

        whether the corresponding `tax_ids` field is available for the customer.
        For more information, 

        see [Invoice recipient tax
        IDs](https://developer.squareup.com/docs/invoices-api/overview#recipient-tax-ids).
      x-release-status: PUBLIC
      properties:
        eu_vat:
          type: string
          description: >-
            The EU VAT identification number for the invoice recipient. For
            example, `IE3426675K`.
          readOnly: true
    InvoiceRequestMethod:
      type: string
      enum:
        - EMAIL
        - CHARGE_CARD_ON_FILE
        - SHARE_MANUALLY
        - CHARGE_BANK_ON_FILE
        - SMS
        - SMS_CHARGE_CARD_ON_FILE
        - SMS_CHARGE_BANK_ON_FILE
      x-enum-elements:
        - name: EMAIL
          description: >-
            Directs Square to send invoices, reminders, and receipts to the
            customer using email.

            Square sends the invoice after it is published (either immediately
            or at the `scheduled_at`

            time, if specified in the [invoice](entity:Invoice)).
        - name: CHARGE_CARD_ON_FILE
          description: >-
            Directs Square to charge the card on file on the `due_date`
            specified in the payment request

            and to use email to send invoices, reminders, and receipts.
        - name: SHARE_MANUALLY
          description: >-
            Directs Square to take no specific action on the invoice. In this
            case, the seller 

            (or the application developer) follows up with the customer for
            payment. For example, 

            a seller might collect a payment in the Seller Dashboard or use the
            Point of Sale (POS) application. 

            The seller might also share the URL of the Square-hosted invoice
            page (`public_url`) with the customer requesting payment.
        - name: CHARGE_BANK_ON_FILE
          description: >-
            Directs Square to charge the customer's bank account on file and to
            use email to send invoices, reminders, and receipts.

            The customer must approve the payment.


            The bank on file payment method applies only to invoices that
            sellers create in the Seller Dashboard or other

            Square product. The bank account is provided by the customer during
            the payment flow. You 

            cannot set `CHARGE_BANK_ON_FILE` as a request method using the
            Invoices API.
        - name: SMS
          description: >-
            Directs Square to send invoices and receipts to the customer using
            SMS (text message). Square sends the invoice

            after it is published (either immediately or at the `scheduled_at`
            time, if specified in the [invoice](entity:Invoice)). 


            You cannot set `SMS` as a request method using the Invoices API.
        - name: SMS_CHARGE_CARD_ON_FILE
          description: >-
            Directs Square to charge the card on file on the `due_date`
            specified in the payment request and to

            use SMS (text message) to send invoices and receipts. 


            You cannot set `SMS_CHARGE_CARD_ON_FILE` as a request method using
            the Invoices API.
        - name: SMS_CHARGE_BANK_ON_FILE
          description: >-
            Directs Square to charge the customer's bank account on file and to
            use SMS (text message) to send invoices and receipts.

            The customer must approve the payment.


            The bank on file payment method applies only to invoices that
            sellers create in the Seller Dashboard

            or other Square product. The bank account is provided by the
            customer during the payment flow. 

            You cannot set `SMS_CHARGE_BANK_ON_FILE` as a request method using
            the Invoices API.
      description: >-
        Specifies the action for Square to take for processing the invoice. For
        example, 

        email the invoice, charge a customer's card on file, or do nothing.
        DEPRECATED at

        version 2021-01-21. The corresponding `request_method` field is replaced
        by the

        `Invoice.delivery_method` and
        `InvoicePaymentRequest.automatic_payment_source` fields.
      x-release-status: DEPRECATED
    InvoiceRequestType:
      type: string
      enum:
        - BALANCE
        - DEPOSIT
        - INSTALLMENT
      x-enum-elements:
        - name: BALANCE
          description: >-
            A request for a balance payment. The balance amount is computed as
            follows: 


            - If the invoice specifies only a balance payment request, the
            balance amount is the 

            total amount of the associated order. 

            - If the invoice also specifies a deposit request, the balance
            amount is the amount 

            remaining after the deposit.


            `INSTALLMENT` and `BALANCE` payment requests are not allowed in the
            same invoice.
        - name: DEPOSIT
          description: >-
            A request for a deposit payment. You have the option of specifying 

            an exact amount or a percentage of the total order amount. If you
            request a deposit, 

            it must be due before any other payment requests.
        - name: INSTALLMENT
          description: >-
            A request for an installment payment. Installments allow buyers to
            pay the invoice over time. Installments can optionally be combined
            with a deposit. 


            Adding `INSTALLMENT` payment requests to an invoice requires an 

            [Invoices Plus
            subscription](https://developer.squareup.com/docs/invoices-api/overview#invoices-plus-subscription).
      description: >-
        Indicates the type of the payment request. For more information, see 

        [Configuring payment
        requests](https://developer.squareup.com/docs/invoices-api/create-publish-invoices#payment-requests).
      x-release-status: PUBLIC
    InvoiceSort:
      type: object
      description: Identifies the sort field and sort order.
      x-release-status: PUBLIC
      required:
        - field
      properties:
        field:
          $ref: '#/components/schemas/InvoiceSortField'
          description: |-
            The field to use for sorting.
            See [InvoiceSortField](#type-invoicesortfield) for possible values
        order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            The order to use for sorting the results.
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
    InvoiceSortField:
      type: string
      enum:
        - INVOICE_SORT_DATE
      x-enum-elements:
        - name: INVOICE_SORT_DATE
          description: >-
            The field works as follows:


            - If the invoice is a draft, it uses the invoice `created_at` date.

            - If the invoice is scheduled for publication, it uses the
            `scheduled_at` date.

            - If the invoice is published, it uses the invoice publication date.
      description: The field to use for sorting.
      x-release-status: PUBLIC
    InvoiceStatus:
      type: string
      enum:
        - DRAFT
        - UNPAID
        - SCHEDULED
        - PARTIALLY_PAID
        - PAID
        - PARTIALLY_REFUNDED
        - REFUNDED
        - CANCELED
        - FAILED
        - PAYMENT_PENDING
      x-enum-elements:
        - name: DRAFT
          description: >-
            The invoice is a draft. You must publish a draft invoice before
            Square can process it.

            A draft invoice has no `public_url`, so it is not available to
            customers.
        - name: UNPAID
          description: The invoice is published but not yet paid.
        - name: SCHEDULED
          description: >-
            The invoice is scheduled to be processed. On the scheduled date,

            Square sends the invoice, initiates an automatic payment, or takes
            no action, depending on

            the delivery method and payment request settings. Square also sets
            the invoice status to the

            appropriate state: `UNPAID`, `PAID`, `PARTIALLY_PAID`, or
            `PAYMENT_PENDING`.
        - name: PARTIALLY_PAID
          description: A partial payment is received for the invoice.
        - name: PAID
          description: The customer paid the invoice in full.
        - name: PARTIALLY_REFUNDED
          description: >-
            The invoice is paid (or partially paid) and some but not all the
            amount paid is

            refunded.
        - name: REFUNDED
          description: The full amount that the customer paid for the invoice is refunded.
        - name: CANCELED
          description: >-
            The invoice is canceled. Square no longer requests payments from the
            customer.

            The `public_url` page remains and is accessible, but it displays the
            invoice

            as canceled and does not accept payment.
        - name: FAILED
          description: Square canceled the invoice due to suspicious activity.
        - name: PAYMENT_PENDING
          description: >-
            A payment on the invoice was initiated but has not yet been
            processed.


            When in this state, invoices cannot be updated and other payments
            cannot be initiated.
      description: Indicates the status of an invoice.
      x-release-status: PUBLIC
    ItemVariationLocationOverrides:
      type: object
      description: >-
        Price and inventory alerting overrides for a `CatalogItemVariation` at a
        specific `Location`.
      x-release-status: PUBLIC
      properties:
        location_id:
          type: string
          description: >-
            The ID of the `Location`. This can include locations that are
            deactivated.
          nullable: true
        price_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The price of the `CatalogItemVariation` at the given `Location`, or
            blank for variable pricing.
          nullable: true
        pricing_type:
          $ref: '#/components/schemas/CatalogPricingType'
          description: >-
            The pricing type (fixed or variable) for the `CatalogItemVariation`
            at the given `Location`.

            See [CatalogPricingType](#type-catalogpricingtype) for possible
            values
          nullable: true
        track_inventory:
          type: boolean
          description: >-
            If `true`, inventory tracking is active for the
            `CatalogItemVariation` at this `Location`.
          nullable: true
        inventory_alert_type:
          $ref: '#/components/schemas/InventoryAlertType'
          description: >-
            Indicates whether the `CatalogItemVariation` displays an alert when
            its inventory

            quantity is less than or equal to its `inventory_alert_threshold`.

            See [InventoryAlertType](#type-inventoryalerttype) for possible
            values
          nullable: true
        inventory_alert_threshold:
          type: integer
          description: >-
            If the inventory quantity for the variation is less than or equal to
            this value and `inventory_alert_type`

            is `LOW_QUANTITY`, the variation displays an alert in the merchant
            dashboard.


            This value is always an integer.
          format: int64
          nullable: true
        sold_out:
          type: boolean
          description: >-
            Indicates whether the overridden item variation is sold out at the
            specified location.


            When inventory tracking is enabled on the item variation either
            globally or at the specified location,

            the item variation is automatically marked as sold out when its
            inventory count reaches zero. The seller

            can manually set the item variation as sold out even when the
            inventory count is greater than zero.

            Attempts by an application to set this attribute are ignored.
            Regardless how the sold-out status is set,

            applications should treat its inventory count as zero when this
            attribute value is `true`.
          readOnly: true
        sold_out_valid_until:
          type: string
          description: >-
            The seller-assigned timestamp, of the RFC 3339 format, to indicate
            when this sold-out variation

            becomes available again at the specified location. Attempts by an
            application to set this attribute are ignored.

            When the current time is later than this attribute value, the
            affected item variation is no longer sold out.
          readOnly: true
    Job:
      type: object
      description: >-
        Represents a job that can be assigned to [team
        members](entity:TeamMember). This object defines the

        job's title and tip eligibility. Compensation is defined in a [job
        assignment](entity:JobAssignment)

        in a team member's wage setting.
      x-release-status: BETA
      properties:
        id:
          type: string
          description: >-
            **Read only** The unique Square-assigned ID of the job. If you need
            a job ID for an API request,

            call [ListJobs](api-endpoint:Team-ListJobs) or use the ID returned
            when you created the job.

            You can also get job IDs from a team member's wage setting.
        title:
          type: string
          description: The title of the job.
          maxLength: 150
          nullable: true
        is_tip_eligible:
          type: boolean
          description: Indicates whether team members can earn tips for the job.
          nullable: true
        created_at:
          type: string
          description: The timestamp when the job was created, in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: The timestamp when the job was last updated, in RFC 3339 format.
          readOnly: true
        version:
          type: integer
          description: >-
            **Read only** The current version of the job. Include this field in
            `UpdateJob` requests to enable

            [optimistic
            concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency)

            control and avoid overwrites from concurrent requests. Requests fail
            if the provided version doesn't

            match the server version at the time of the request.
    JobAssignment:
      type: object
      description: >-
        Represents a job assigned to a [team member](entity:TeamMember),
        including the compensation the team

        member earns for the job. Job assignments are listed in the team
        member's [wage setting](entity:WageSetting).
      x-release-status: PUBLIC
      required:
        - pay_type
      properties:
        job_title:
          type: string
          description: The title of the job.
          nullable: true
        pay_type:
          $ref: '#/components/schemas/JobAssignmentPayType'
          description: >-
            The current pay type for the job assignment used to

            calculate the pay amount in a pay period.

            See [JobAssignmentPayType](#type-jobassignmentpaytype) for possible
            values
        hourly_rate:
          $ref: '#/components/schemas/Money'
          description: >-
            The hourly pay rate of the job. For `SALARY` pay types, Square
            calculates the hourly rate based on

            `annual_rate` and `weekly_hours`.
          nullable: true
        annual_rate:
          $ref: '#/components/schemas/Money'
          description: >-
            The total pay amount for a 12-month period on the job. Set if the
            job `PayType` is `SALARY`.
          nullable: true
        weekly_hours:
          type: integer
          description: >-
            The planned hours per week for the job. Set if the job `PayType` is
            `SALARY`.
          nullable: true
        job_id:
          type: string
          description: The ID of the [job](entity:Job).
          x-release-status: BETA
          nullable: true
    JobAssignmentPayType:
      type: string
      enum:
        - NONE
        - HOURLY
        - SALARY
      x-enum-elements:
        - name: NONE
          description: The job does not have a defined pay type.
        - name: HOURLY
          description: The job pays an hourly rate.
        - name: SALARY
          description: The job pays an annual salary.
      description: Enumerates the possible pay types that a job can be assigned.
      x-release-status: PUBLIC
    LinkCustomerToGiftCardRequest:
      type: object
      description: A request to link a customer to a gift card.
      x-release-status: PUBLIC
      x-params-example: '?gift_card_id=gftc:71ea002277a34f8a945e284b04822edb'
      required:
        - customer_id
      properties:
        customer_id:
          type: string
          description: The ID of the customer to link to the gift card.
          minLength: 1
          maxLength: 191
      example:
        customer_id: GKY0FZ3V717AH8Q2D821PNT2ZW
    LinkCustomerToGiftCardResponse:
      type: object
      description: >-
        A response that contains the linked `GiftCard` object. If the request
        resulted in errors, 

        the response contains a set of `Error` objects.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        gift_card:
          $ref: '#/components/schemas/GiftCard'
          description: >-
            The gift card with the ID of the linked customer listed in the
            `customer_ids` field.
      example:
        gift_card:
          balance_money:
            amount: 2500
            currency: USD
          created_at: '2021-03-25T05:13:01Z'
          customer_ids:
            - GKY0FZ3V717AH8Q2D821PNT2ZW
          gan: '7783320005440920'
          gan_source: SQUARE
          id: gftc:71ea002277a34f8a945e284b04822edb
          state: ACTIVE
          type: DIGITAL
    ListBankAccountsRequest:
      type: object
      description: |-
        Request object for fetching all `BankAccount`
        objects linked to a account.
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: >-
            The pagination cursor returned by a previous call to this endpoint.

            Use it in the next `ListBankAccounts` request to retrieve the next
            set 

            of results.


            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
          nullable: true
        limit:
          type: integer
          description: >-
            Upper limit on the number of bank accounts to return in the
            response. 

            Currently, 1000 is the largest supported limit. You can specify a
            limit 

            of up to 1000 bank accounts. This is also the default limit.
          nullable: true
        location_id:
          type: string
          description: >-
            Location ID. You can specify this optional filter 

            to retrieve only the linked bank accounts belonging to a specific
            location.
          nullable: true
    ListBankAccountsResponse:
      type: object
      description: Response object returned by ListBankAccounts.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        bank_accounts:
          type: array
          items:
            $ref: '#/components/schemas/BankAccount'
          description: List of BankAccounts associated with this account.
        cursor:
          type: string
          description: >-
            When a response is truncated, it includes a cursor that you can 

            use in a subsequent request to fetch next set of bank accounts.

            If empty, this is the final response.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
      example:
        bank_accounts:
          - account_number_suffix: '971'
            account_type: CHECKING
            bank_name: Bank Name
            country: US
            creditable: false
            currency: USD
            debitable: false
            holder_name: Jane Doe
            id: ao6iaQ9vhDiaQD7n3GB
            location_id: S8GWD5example
            primary_bank_identification_number: '112200303'
            status: VERIFICATION_IN_PROGRESS
            version: 5
          - account_number_suffix: '972'
            account_type: CHECKING
            bank_name: Bank Name
            country: US
            creditable: false
            currency: USD
            debitable: false
            holder_name: Jane Doe
            id: 4x7WXuaxrkQkVlka3GB
            location_id: S8GWD5example
            primary_bank_identification_number: '112200303'
            status: VERIFICATION_IN_PROGRESS
            version: 5
    ListBookingCustomAttributeDefinitionsRequest:
      type: object
      description: >-
        Represents a
        [ListBookingCustomAttributeDefinitions](api-endpoint:BookingCustomAttributes-ListBookingCustomAttributeDefinitions)
        request.
      x-release-status: PUBLIC
      properties:
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          minimum: 1
          maximum: 100
          nullable: true
        cursor:
          type: string
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
    ListBookingCustomAttributeDefinitionsResponse:
      type: object
      description: >-
        Represents a
        [ListBookingCustomAttributeDefinitions](api-endpoint:BookingCustomAttributes-ListBookingCustomAttributeDefinitions)
        response.

        Either `custom_attribute_definitions`, an empty object, or `errors` is
        present in the response.

        If additional results are available, the `cursor` field is also present
        along with `custom_attribute_definitions`.
      x-release-status: PUBLIC
      properties:
        custom_attribute_definitions:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The retrieved custom attribute definitions. If no custom attribute
            definitions are found,

            Square returns an empty object (`{}`).
        cursor:
          type: string
          description: >-
            The cursor to provide in your next call to this endpoint to retrieve
            the next page of

            results for your original request. This field is present only if the
            request succeeded and

            additional results are available. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        cursor: >-
          YEk4UPbUEsu8MUV0xouO5hCiFcD9T5ztB6UWEJq5vZnqBFmoBEi0j1j6HWYTFGMRre4p7T5wAQBj3Th1NX3XgBFcQVEVsIxUQ2NsbwjRitfoEZDml9uxxQXepowyRvCuSThHPbJSn7M7wInl3x8XypQF9ahVVQXegJ0CxEKc0SBH
        custom_attribute_definitions:
          - created_at: '2022-11-16T15:27:30Z'
            description: Update the description as desired.
            key: favoriteShampoo
            name: Favorite shampoo
            schema:
              $ref: >-
                https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
            updated_at: '2022-11-16T15:39:38Z'
            version: 3
            visibility: VISIBILITY_READ_ONLY
          - created_at: '2022-11-16T15:49:05Z'
            description: Number of people in the party for dine-in
            key: partySize
            name: Party size
            schema:
              $ref: >-
                https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number
            updated_at: '2022-11-16T15:49:05Z'
            version: 1
            visibility: VISIBILITY_HIDDEN
        errors: []
    ListBookingCustomAttributesRequest:
      type: object
      description: >-
        Represents a
        [ListBookingCustomAttributes](api-endpoint:BookingCustomAttributes-ListBookingCustomAttributes)
        request.
      x-release-status: PUBLIC
      properties:
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          minimum: 1
          maximum: 100
          nullable: true
        cursor:
          type: string
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request. For more

            information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        with_definitions:
          type: boolean
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of each

            custom attribute. Set this parameter to `true` to get the name and
            description of each custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          nullable: true
    ListBookingCustomAttributesResponse:
      type: object
      description: >-
        Represents a
        [ListBookingCustomAttributes](api-endpoint:BookingCustomAttributes-ListBookingCustomAttributes)
        response.

        Either `custom_attributes`, an empty object, or `errors` is present in
        the response. If additional

        results are available, the `cursor` field is also present along with
        `custom_attributes`.
      x-release-status: PUBLIC
      properties:
        custom_attributes:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The retrieved custom attributes. If `with_definitions` was set to
            `true` in the request,

            the custom attribute definition is returned in the `definition`
            field of each custom attribute.


            If no custom attributes are found, Square returns an empty object
            (`{}`).
        cursor:
          type: string
          description: >-
            The cursor to use in your next call to this endpoint to retrieve the
            next page of results

            for your original request. This field is present only if the request
            succeeded and additional

            results are available. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attributes:
          - created_at: '2022-11-16T15:50:27Z'
            key: favoriteShampoo
            updated_at: '2022-11-16T15:50:27Z'
            value: Hydro-Cool
            version: 1
            visibility: VISIBILITY_READ_ONLY
          - created_at: '2022-11-16T15:51:53Z'
            key: hasShoes
            updated_at: '2022-11-16T15:51:53Z'
            value: false
            version: 1
            visibility: VISIBILITY_HIDDEN
        errors: []
    ListBookingsRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        limit:
          type: integer
          description: >-
            The maximum number of results per page to return in a paged
            response.
          minimum: 1
          maximum: 10000
          nullable: true
        cursor:
          type: string
          description: >-
            The pagination cursor from the preceding response to return the next
            page of the results. Do not set this when retrieving the first page
            of the results.
          maxLength: 65536
          nullable: true
        customer_id:
          type: string
          description: >-
            The [customer](entity:Customer) for whom to retrieve bookings. If
            this is not set, bookings for all customers are retrieved.
          maxLength: 192
          nullable: true
        team_member_id:
          type: string
          description: >-
            The team member for whom to retrieve bookings. If this is not set,
            bookings of all members are retrieved.
          maxLength: 32
          nullable: true
        location_id:
          type: string
          description: >-
            The location for which to retrieve bookings. If this is not set, all
            locations' bookings are retrieved.
          maxLength: 32
          nullable: true
        start_at_min:
          type: string
          description: >-
            The RFC 3339 timestamp specifying the earliest of the start time. If
            this is not set, the current time is used.
          nullable: true
        start_at_max:
          type: string
          description: >-
            The RFC 3339 timestamp specifying the latest of the start time. If
            this is not set, the time of 31 days after `start_at_min` is used.
          nullable: true
    ListBookingsResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        bookings:
          type: array
          items:
            $ref: '#/components/schemas/Booking'
          description: The list of targeted bookings.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in the subsequent request to get
            the next page of the results. Stop retrieving the next page of the
            results when the cursor is not set.
          maxLength: 65536
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
      example:
        bookings:
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMXUrsBWWcHTt79t
            created_at: '2020-10-28T15:47:41Z'
            customer_id: EX2QSVGTZN4K1E5QE1CBFNVQ8M
            customer_note: ''
            id: zkras0xv0xwswx
            location_id: LEQHH0YY8B42M
            seller_note: ''
            start_at: '2020-11-26T13:00:00Z'
            status: ACCEPTED
            updated_at: '2020-10-28T15:49:25Z'
            version: 1
        cursor: null
        errors: []
    ListBreakTypesRequest:
      type: object
      description: A request for a filtered set of `BreakType` objects.
      x-release-status: PUBLIC
      x-params-example: >-
        ?location_id=PAA1RJZZKXBFG&limit=2&cursor=s4R0Z6ecFTzTC4jz8sUDBQTudX3KE313OT9fCt3VUgsXM4sMgED
      properties:
        location_id:
          type: string
          description: >-
            Filter the returned `BreakType` results to only those that are
            associated with the

            specified location.
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of `BreakType` results to return per page. The
            number can range between 1

            and 200. The default is 200.
          minimum: 1
          maximum: 200
          nullable: true
        cursor:
          type: string
          description: A pointer to the next page of `BreakType` results to fetch.
          nullable: true
    ListBreakTypesResponse:
      type: object
      description: >-
        The response to a request for a set of `BreakType` objects. The response
        contains

        the requested `BreakType` objects and might contain a set of `Error`
        objects if

        the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        break_types:
          type: array
          items:
            $ref: '#/components/schemas/BreakType'
          description: ' A page of `BreakType` results.'
        cursor:
          type: string
          description: |-
            The value supplied in the subsequent request to fetch the next page
            of `BreakType` results.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        break_types:
          - break_name: Coffee Break
            created_at: '2019-01-22T20:47:37Z'
            expected_duration: PT5M
            id: REGS1EQR1TPZ5
            is_paid: false
            location_id: PAA1RJZZKXBFG
            updated_at: '2019-01-22T20:47:37Z'
            version: 1
          - break_name: Lunch Break
            created_at: '2019-01-25T19:26:30Z'
            expected_duration: PT1H
            id: 92EPDRQKJ5088
            is_paid: true
            location_id: PAA1RJZZKXBFG
            updated_at: '2019-01-25T19:26:30Z'
            version: 3
        cursor: 2fofTniCgT0yIPAq26kmk0YyFQJZfbWkh73OOnlTHmTAx13NgED
    ListCardsRequest:
      type: object
      description: |-
        Retrieves details for a specific Card. Accessible via
        HTTP requests at GET https://connect.squareup.com/v2/cards
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for your original
            query.


            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
          maxLength: 256
          nullable: true
        customer_id:
          type: string
          description: |-
            Limit results to cards associated with the customer supplied.
            By default, all cards owned by the merchant are returned.
          nullable: true
        include_disabled:
          type: boolean
          description: |-
            Includes disabled cards.
            By default, all enabled cards owned by the merchant are returned.
          nullable: true
        reference_id:
          type: string
          description: Limit results to cards associated with the reference_id supplied.
          nullable: true
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: >-
            Sorts the returned list by when the card was created with the
            specified order.

            This field defaults to ASC.

            See [SortOrder](#type-sortorder) for possible values
          nullable: true
      example: {}
    ListCardsResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [ListCards](api-endpoint:Cards-ListCards) endpoint.


        Note: if there are errors processing the request, the card field will
        not be

        present.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        cards:
          type: array
          items:
            $ref: '#/components/schemas/Card'
          description: The requested list of `Card`s.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,

            this is the final response.


            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
      example:
        cards:
          - billing_address:
              address_line_1: 500 Electric Ave
              address_line_2: Suite 600
              administrative_district_level_1: NY
              country: US
              locality: New York
              postal_code: '10003'
            bin: '411111'
            card_brand: VISA
            card_type: CREDIT
            cardholder_name: Amelia Earhart
            customer_id: VDKXEEKPJN48QDG3BGGFAK05P8
            enabled: true
            exp_month: 11
            exp_year: 2022
            fingerprint: >-
              ex-p-cs80EK9Flz7LsCMv-szbptQ_ssAGrhemzSTsPFgt9nzyE6t7okiLIQc-qw_quqKX4Q
            id: ccof:uIbfJXhXETSP197M3GB
            last_4: '1111'
            merchant_id: 6SSW7HV8K2ST5
            prepaid_type: NOT_PREPAID
            reference_id: user-id-1
            version: 1
    ListCashDrawerShiftEventsRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - location_id
      properties:
        location_id:
          type: string
          description: The ID of the location to list cash drawer shifts for.
          minLength: 1
        limit:
          type: integer
          description: |-
            Number of resources to be returned in a page of results (200 by
            default, 1000 max).
          maximum: 1000
          nullable: true
        cursor:
          type: string
          description: Opaque cursor for fetching the next page of results.
          nullable: true
      example: {}
    ListCashDrawerShiftEventsResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: |-
            Opaque cursor for fetching the next page. Cursor is not present in
            the last page of results.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        cash_drawer_shift_events:
          type: array
          items:
            $ref: '#/components/schemas/CashDrawerShiftEvent'
          description: |-
            All of the events (payments, refunds, etc.) for a cash drawer during
            the shift.
      example:
        cash_drawer_shift_events:
          - created_at: '2019-11-22T00:43:02.000Z'
            description: ''
            event_money:
              amount: 100
              currency: USD
            event_type: CASH_TENDER_PAYMENT
            id: 9F07DB01-D85A-4B77-88C3-D5C64CEB5155
            team_member_id: ''
          - created_at: '2019-11-22T00:43:12.000Z'
            description: ''
            event_money:
              amount: 250
              currency: USD
            event_type: CASH_TENDER_PAYMENT
            id: B2854CEA-A781-49B3-8F31-C64558231F48
            team_member_id: ''
          - created_at: '2019-11-22T00:43:23.000Z'
            description: ''
            event_money:
              amount: 250
              currency: USD
            event_type: CASH_TENDER_CANCELLED_PAYMENT
            id: B5FB7F72-95CD-44A3-974D-26C41064D042
            team_member_id: ''
          - created_at: '2019-11-22T00:43:46.000Z'
            description: ''
            event_money:
              amount: 100
              currency: USD
            event_type: CASH_TENDER_REFUND
            id: 0B425480-8504-40B4-A867-37B23543931B
            team_member_id: ''
          - created_at: '2019-11-22T00:44:18.000Z'
            description: Transfer from another drawer
            event_money:
              amount: 10000
              currency: USD
            event_type: PAID_IN
            id: 8C66E60E-FDCF-4EEF-A98D-3B14B7ED5CBE
            team_member_id: ''
          - created_at: '2019-11-22T00:44:29.000Z'
            description: Transfer out to another drawer
            event_money:
              amount: 10000
              currency: USD
            event_type: PAID_OUT
            id: D5ACA7FE-C64D-4ADA-8BC8-82118A2DAE4F
            team_member_id: ''
    ListCashDrawerShiftsRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - location_id
      properties:
        location_id:
          type: string
          description: The ID of the location to query for a list of cash drawer shifts.
          minLength: 1
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            The order in which cash drawer shifts are listed in the response,
            based on their opened_at field. Default value: ASC
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
        begin_time:
          type: string
          description: >-
            The inclusive start time of the query on opened_at, in ISO 8601
            format.
          nullable: true
        end_time:
          type: string
          description: >-
            The exclusive end date of the query on opened_at, in ISO 8601
            format.
          nullable: true
        limit:
          type: integer
          description: |-
            Number of cash drawer shift events in a page of results (200 by
            default, 1000 max).
          maximum: 1000
          nullable: true
        cursor:
          type: string
          description: Opaque cursor for fetching the next page of results.
          nullable: true
      example: {}
    ListCashDrawerShiftsResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: |-
            Opaque cursor for fetching the next page of results. Cursor is not
            present in the last page of results.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        cash_drawer_shifts:
          type: array
          items:
            $ref: '#/components/schemas/CashDrawerShiftSummary'
          description: |-
            A collection of CashDrawerShiftSummary objects for shifts that match
            the query.
      example:
        cash_drawer_shifts:
          - closed_at: '2019-11-22T00:44:49.000Z'
            closed_cash_money:
              amount: 9970
              currency: USD
            description: Misplaced some change
            ended_at: '2019-11-22T00:44:49.000Z'
            expected_cash_money:
              amount: 10000
              currency: USD
            id: DCC99978-09A6-4926-849F-300BE9C5793A
            opened_at: '2019-11-22T00:42:54.000Z'
            opened_cash_money:
              amount: 10000
              currency: USD
            state: CLOSED
    ListCatalogRequest:
      type: object
      x-release-status: PUBLIC
      x-params-example: '?types=category,tax'
      properties:
        cursor:
          type: string
          description: >-
            The pagination cursor returned in the previous response. Leave unset
            for an initial request.

            The page size is currently set to be 100.

            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
          nullable: true
        types:
          type: string
          description: >-
            An optional case-insensitive, comma-separated list of object types
            to retrieve.


            The valid values are defined in the
            [CatalogObjectType](entity:CatalogObjectType) enum, for example,

            `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,

            `MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.


            If this is unspecified, the operation returns objects of all the top
            level types at the version

            of the Square API used to make the request. Object types that are
            nested onto other object types

            are not included in the defaults.


            At the current API version the default object types are:

            ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, 

            PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,

            SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION,
            QUICK_AMOUNT_SETTINGS.
          nullable: true
        catalog_version:
          type: integer
          description: >-
            The specific version of the catalog objects to be included in the
            response.

            This allows you to retrieve historical versions of objects. The
            specified version value is matched against

            the [CatalogObject](entity:CatalogObject)s' `version` attribute.  If
            not included, results will be from the

            current version of the catalog.
          format: int64
          x-release-status: BETA
          nullable: true
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/Catalog/ListCatalog/ListCatalogRequest.csharp
        java: /sdk_samples/Catalog/ListCatalog/ListCatalogRequest.java
        javascript: /sdk_samples/Catalog/ListCatalog/ListCatalogRequest.javascript
        php: /sdk_samples/Catalog/ListCatalog/ListCatalogRequest.php
        python: /sdk_samples/Catalog/ListCatalog/ListCatalogRequest.python
        ruby: /sdk_samples/Catalog/ListCatalog/ListCatalogRequest.ruby
    ListCatalogResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If unset,
            this is the final response.

            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
        objects:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: The CatalogObjects returned.
      example:
        objects:
          - category_data:
              name: Beverages
            id: 5ZYQZZ2IECPVJ2IJ5KQPRDC3
            is_deleted: false
            present_at_all_locations: true
            type: CATEGORY
            updated_at: '2017-02-21T14:50:26.495Z'
            version: 1487688626495
          - id: L5R47DGBZOOVKCAFIXC56AEN
            is_deleted: false
            present_at_all_locations: true
            tax_data:
              calculation_phase: TAX_SUBTOTAL_PHASE
              enabled: true
              inclusion_type: ADDITIVE
              name: Sales Tax
              percentage: '5.0'
            type: TAX
            updated_at: '2017-02-21T14:50:26.495Z'
            version: 1487688626495
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/Catalog/ListCatalog/ListCatalogResponse.csharp
        java: /sdk_samples/Catalog/ListCatalog/ListCatalogResponse.java
        javascript: /sdk_samples/Catalog/ListCatalog/ListCatalogResponse.javascript
        php: /sdk_samples/Catalog/ListCatalog/ListCatalogResponse.php
        python: /sdk_samples/Catalog/ListCatalog/ListCatalogResponse.python
        ruby: /sdk_samples/Catalog/ListCatalog/ListCatalogResponse.ruby
    ListCustomerCustomAttributeDefinitionsRequest:
      type: object
      description: >-
        Represents a
        [ListCustomerCustomAttributeDefinitions](api-endpoint:CustomerCustomAttributes-ListCustomerCustomAttributeDefinitions)
        request.
      x-release-status: PUBLIC
      x-params-example: '?limit=2'
      properties:
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          minimum: 1
          maximum: 100
          nullable: true
        cursor:
          type: string
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
    ListCustomerCustomAttributeDefinitionsResponse:
      type: object
      description: >-
        Represents a
        [ListCustomerCustomAttributeDefinitions](api-endpoint:CustomerCustomAttributes-ListCustomerCustomAttributeDefinitions)
        response.

        Either `custom_attribute_definitions`, an empty object, or `errors` is
        present in the response.

        If additional results are available, the `cursor` field is also present
        along with `custom_attribute_definitions`.
      x-release-status: PUBLIC
      properties:
        custom_attribute_definitions:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The retrieved custom attribute definitions. If no custom attribute
            definitions are found,

            Square returns an empty object (`{}`).
        cursor:
          type: string
          description: >-
            The cursor to provide in your next call to this endpoint to retrieve
            the next page of

            results for your original request. This field is present only if the
            request succeeded and

            additional results are available. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        cursor: >-
          YEk4UPbUEsu8MUV0xouO5hCiFcD9T5ztB6UWEJq5vZnqBFmoBEi0j1j6HWYTFGMRre4p7T5wAQBj3Th1NX3XgBFcQVEVsIxUQ2NsbwjRitfoEZDml9uxxQXepowyRvCuSThHPbJSn7M7wInl3x8XypQF9ahVVQXegJ0CxEKc0SBH
        custom_attribute_definitions:
          - created_at: '2022-04-26T15:27:30Z'
            description: Update the description as desired.
            key: favoritemovie
            name: Favorite Movie
            schema:
              $ref: >-
                https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
            updated_at: '2022-04-26T15:39:38Z'
            version: 3
            visibility: VISIBILITY_READ_ONLY
          - created_at: '2022-04-26T15:49:05Z'
            description: Customer owns movie.
            key: ownsmovie
            name: Owns Movie
            schema:
              $ref: >-
                https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Boolean
            updated_at: '2022-04-26T15:49:05Z'
            version: 1
            visibility: VISIBILITY_HIDDEN
    ListCustomerCustomAttributesRequest:
      type: object
      description: >-
        Represents a
        [ListCustomerCustomAttributes](api-endpoint:CustomerCustomAttributes-ListCustomerCustomAttributes)
        request.
      x-release-status: PUBLIC
      x-params-example: '?customer_id=Z57QXKM2FGXEQDV42W8RBZY7BR'
      properties:
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          minimum: 1
          maximum: 100
          nullable: true
        cursor:
          type: string
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request. For more

            information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        with_definitions:
          type: boolean
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of each

            custom attribute. Set this parameter to `true` to get the name and
            description of each custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          nullable: true
    ListCustomerCustomAttributesResponse:
      type: object
      description: >-
        Represents a
        [ListCustomerCustomAttributes](api-endpoint:CustomerCustomAttributes-ListCustomerCustomAttributes)
        response.

        Either `custom_attributes`, an empty object, or `errors` is present in
        the response. If additional

        results are available, the `cursor` field is also present along with
        `custom_attributes`.
      x-release-status: PUBLIC
      properties:
        custom_attributes:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The retrieved custom attributes. If `with_definitions` was set to
            `true` in the request,

            the custom attribute definition is returned in the `definition`
            field of each custom attribute.


            If no custom attributes are found, Square returns an empty object
            (`{}`).
        cursor:
          type: string
          description: >-
            The cursor to use in your next call to this endpoint to retrieve the
            next page of results

            for your original request. This field is present only if the request
            succeeded and additional

            results are available. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attributes:
          - created_at: '2022-04-26T15:50:27Z'
            key: favoritemovie
            updated_at: '2022-04-26T15:50:27Z'
            value: Dune
            version: 1
            visibility: VISIBILITY_READ_ONLY
          - created_at: '2022-04-26T15:51:53Z'
            key: ownsmovie
            updated_at: '2022-04-26T15:51:53Z'
            value: false
            version: 1
            visibility: VISIBILITY_HIDDEN
    ListCustomerGroupsRequest:
      type: object
      description: >-
        Defines the query parameters that can be included in a request to the

        [ListCustomerGroups](api-endpoint:CustomerGroups-ListCustomerGroups)
        endpoint.
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for your
            original query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single page. This limit
            is advisory. The response might contain more or fewer results.

            If the limit is less than 1 or greater than 50, Square returns a
            `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value
            is 50.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          minimum: 1
          maximum: 50
          nullable: true
      example: {}
    ListCustomerGroupsResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [ListCustomerGroups](api-endpoint:CustomerGroups-ListCustomerGroups)
        endpoint.


        Either `errors` or `groups` is present in a given response (never both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        groups:
          type: array
          items:
            $ref: '#/components/schemas/CustomerGroup'
          description: A list of customer groups belonging to the current seller.
        cursor:
          type: string
          description: >-
            A pagination cursor to retrieve the next set of results for your

            original query to the endpoint. This value is present only if the
            request

            succeeded and additional results are available.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        groups:
          - created_at: '2020-04-13T21:54:57.863Z'
            id: 2TAT3CMH4Q0A9M87XJZED0WMR3
            name: Loyal Customers
            updated_at: '2020-04-13T21:54:58Z'
          - created_at: '2020-04-13T21:55:18.795Z'
            id: 4XMEHESXJBNE9S9JAKZD2FGB14
            name: Super Loyal Customers
            updated_at: '2020-04-13T21:55:19Z'
    ListCustomerSegmentsRequest:
      type: object
      description: >-
        Defines the valid parameters for requests to the `ListCustomerSegments`
        endpoint.
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: >-
            A pagination cursor returned by previous calls to
            `ListCustomerSegments`.

            This cursor is used to retrieve the next set of query results.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single page. This limit
            is advisory. The response might contain more or fewer results.

            If the specified limit is less than 1 or greater than 50, Square
            returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The
            default value is 50.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          minimum: 1
          maximum: 50
          nullable: true
      example: {}
    ListCustomerSegmentsResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body for requests
        to the `ListCustomerSegments` endpoint.


        Either `errors` or `segments` is present in a given response (never
        both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        segments:
          type: array
          items:
            $ref: '#/components/schemas/CustomerSegment'
          description: >-
            The list of customer segments belonging to the associated Square
            account.
        cursor:
          type: string
          description: >-
            A pagination cursor to be used in subsequent calls to
            `ListCustomerSegments`

            to retrieve the next set of query results. The cursor is only
            present if the request succeeded and

            additional results are available.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        segments:
          - created_at: '2020-01-09T19:33:24.469Z'
            id: GMNXRZVEXNQDF.CHURN_RISK
            name: Lapsed
            updated_at: '2020-04-13T21:47:04Z'
          - created_at: '2020-01-09T19:33:24.486Z'
            id: GMNXRZVEXNQDF.LOYAL
            name: Regulars
            updated_at: '2020-04-13T21:47:04Z'
          - created_at: '2020-01-09T19:33:21.813Z'
            id: GMNXRZVEXNQDF.REACHABLE
            name: Reachable
            updated_at: '2020-04-13T21:47:04Z'
          - created_at: '2020-01-09T19:33:25Z'
            id: gv2:KF92J19VXN5FK30GX2E8HSGQ20
            name: Instant Profile
            updated_at: '2020-04-13T23:01:03Z'
    ListCustomersRequest:
      type: object
      description: |-
        Defines the query parameters that can be included in a request to the
        `ListCustomers` endpoint.
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for your
            original query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single page. This limit
            is advisory. The response might contain more or fewer results.

            If the specified limit is less than 1 or greater than 100, Square
            returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The
            default value is 100.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          minimum: 1
          maximum: 100
          nullable: true
        sort_field:
          $ref: '#/components/schemas/CustomerSortField'
          description: |-
            Indicates how customers should be sorted.

            The default value is `DEFAULT`.
            See [CustomerSortField](#type-customersortfield) for possible values
          nullable: true
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            Indicates whether customers should be sorted in ascending (`ASC`) or
            descending (`DESC`) order.

            The default value is `ASC`.
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
        count:
          type: boolean
          description: >-
            Indicates whether to return the total count of customers in the
            `count` field of the response.


            The default value is `false`.
          nullable: true
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/ListCustomers/ListCustomersRequest.csharp
        java: /sdk_samples/ListCustomers/ListCustomersRequest.java
        javascript: /sdk_samples/ListCustomers/ListCustomersRequest.javascript
        php: /sdk_samples/ListCustomers/ListCustomersRequest.php
        python: /sdk_samples/ListCustomers/ListCustomersRequest.python
        ruby: /sdk_samples/ListCustomers/ListCustomersRequest.ruby
    ListCustomersResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the `ListCustomers` endpoint.


        Either `errors` or `customers` is present in a given response (never
        both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        customers:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
          description: >-
            The customer profiles associated with the Square account or an empty
            object (`{}`) if none are found.

            Only customer profiles with public information (`given_name`,
            `family_name`, `company_name`, `email_address`, or

            `phone_number`) are included in the response.
        cursor:
          type: string
          description: >-
            A pagination cursor to retrieve the next set of results for the

            original query. A cursor is only present if the request succeeded
            and additional results

            are available.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        count:
          type: integer
          description: >-
            The total count of customers associated with the Square account.
            Only customer profiles with public information

            (`given_name`, `family_name`, `company_name`, `email_address`, or
            `phone_number`) are counted. This field is present

            only if `count` is set to `true` in the request.
          format: int64
      example:
        customers:
          - address:
              address_line_1: 500 Electric Ave
              address_line_2: Suite 600
              administrative_district_level_1: NY
              country: US
              locality: New York
              postal_code: '10003'
            created_at: '2016-03-23T20:21:54.859Z'
            creation_source: THIRD_PARTY
            email_address: Amelia.Earhart@example.com
            family_name: Earhart
            given_name: Amelia
            group_ids:
              - 545AXB44B4XXWMVQ4W8SBT3HHF
            id: JDKYHBWT1D4F8MFH63DBMEN8Y4
            note: a customer
            phone_number: +1-212-555-4240
            preferences:
              email_unsubscribed: false
            reference_id: YOUR_REFERENCE_ID
            segment_ids:
              - 1KB9JE5EGJXCW.REACHABLE
            updated_at: '2016-03-23T20:21:55Z'
            version: 1
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/ListCustomers/ListCustomersResponse.csharp
        java: /sdk_samples/ListCustomers/ListCustomersResponse.java
        javascript: /sdk_samples/ListCustomers/ListCustomersResponse.javascript
        php: /sdk_samples/ListCustomers/ListCustomersResponse.php
        python: /sdk_samples/ListCustomers/ListCustomersResponse.python
        ruby: /sdk_samples/ListCustomers/ListCustomersResponse.ruby
    ListDeviceCodesRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for your original
            query.


            See [Paginating
            results](https://developer.squareup.com/docs/working-with-apis/pagination)
            for more information.
          nullable: true
        location_id:
          type: string
          description: |-
            If specified, only returns DeviceCodes of the specified location.
            Returns DeviceCodes of all locations if empty.
          nullable: true
        product_type:
          $ref: '#/components/schemas/ProductType'
          description: >-
            If specified, only returns DeviceCodes targeting the specified
            product type.

            Returns DeviceCodes of all product types if empty.
          nullable: true
        status:
          type: array
          items:
            $ref: '#/components/schemas/DeviceCodeStatus'
          description: |-
            If specified, returns DeviceCodes with the specified statuses.
            Returns DeviceCodes of status `PAIRED` and `UNPAIRED` if empty.
            See [DeviceCodeStatus](#type-devicecodestatus) for possible values
          nullable: true
      example: {}
    ListDeviceCodesResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        device_codes:
          type: array
          items:
            $ref: '#/components/schemas/DeviceCode'
          description: The queried DeviceCode.
        cursor:
          type: string
          description: >-
            A pagination cursor to retrieve the next set of results for your

            original query to the endpoint. This value is present only if the
            request

            succeeded and additional results are available.


            See [Paginating
            results](https://developer.squareup.com/docs/working-with-apis/pagination)
            for more information.
      example:
        device_codes:
          - code: EBCARJ
            created_at: '2020-02-06T18:44:33.000Z'
            device_id: 907CS13101300122
            id: B3Z6NAMYQSMTM
            location_id: B5E4484SHHNYH
            name: Counter 1
            pair_by: '2020-02-06T18:49:33.000Z'
            product_type: TERMINAL_API
            status: PAIRED
            status_changed_at: '2020-02-06T18:47:28.000Z'
          - code: GVXNYN
            created_at: '2020-02-07T19:55:04.000Z'
            id: YKGMJMYK8H4PQ
            location_id: A6SYFRSV4WAFW
            name: Unused device code
            pair_by: '2020-02-07T20:00:04.000Z'
            product_type: TERMINAL_API
            status: UNPAIRED
            status_changed_at: '2020-02-07T19:55:04.000Z'
    ListDevicesRequest:
      type: object
      x-release-status: BETA
      properties:
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
          nullable: true
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            The order in which results are listed.
            - `ASC` - Oldest to newest.
            - `DESC` - Newest to oldest (default).
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
        limit:
          type: integer
          description: The number of results to return in a single page.
          minimum: 1
          maximum: 100
          nullable: true
        location_id:
          type: string
          description: If present, only returns devices at the target location.
          nullable: true
      example: {}
    ListDevicesResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors that occurred during the request.
        devices:
          type: array
          items:
            $ref: '#/components/schemas/Device'
          description: The requested list of `Device` objects.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,

            this is the final response.

            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
      example:
        cursor: GcXjlV2iaizH7R0fMT6wUDbw6l4otigjzx8XOOspUKHo9EPLRByM
        devices:
          - attributes:
              manufacturer: Square
              manufacturers_id: 995CS397A6475287
              merchant_token: MLCHNZCBWFDZB
              model: T2
              name: Square Terminal 995
              type: TERMINAL
              updated_at: '2023-09-29T13:04:56.335762883Z'
              version: 5.41.0085
            components:
              - application_details:
                  application_type: TERMINAL_API
                  session_location: LMN2K7S3RTOU3
                  version: '6.25'
                type: APPLICATION
              - card_reader_details:
                  version: 3.53.70
                type: CARD_READER
              - battery_details:
                  external_power: AVAILABLE_CHARGING
                  visible_percent: 5
                type: BATTERY
              - type: WIFI
                wifi_details:
                  active: true
                  ip_address_v4: 10.0.0.7
                  secure_connection: WPA/WPA2 PSK
                  signal_strength:
                    value: 2
                  ssid: Staff Network
              - ethernet_details:
                  active: false
                type: ETHERNET
            id: device:995CS397A6475287
            status:
              category: AVAILABLE
          - attributes:
              manufacturer: Square
              manufacturers_id: 995CS234B5493559
              merchant_token: MLCHXZCBWFGDW
              model: T2
              name: Square Terminal 995
              type: TERMINAL
              updated_at: '2023-09-29T12:39:56.335742073Z'
              version: 5.41.0085
            components:
              - application_details:
                  application_type: TERMINAL_API
                  session_location: LMN2K7S3RTOU3
                  version: '6.25'
                type: APPLICATION
              - card_reader_details:
                  version: 3.53.70
                type: CARD_READER
              - battery_details:
                  external_power: AVAILABLE_CHARGING
                  visible_percent: 24
                type: BATTERY
              - type: WIFI
                wifi_details:
                  active: true
                  ip_address_v4: 10.0.0.7
                  secure_connection: WPA/WPA2 PSK
                  signal_strength:
                    value: 2
                  ssid: Staff Network
              - ethernet_details:
                  active: false
                type: ETHERNET
            id: device:995CS234B5493559
            status:
              category: NEEDS_ATTENTION
    ListDisputeEvidenceRequest:
      type: object
      description: Defines the parameters for a `ListDisputeEvidence` request.
      x-release-status: PUBLIC
      x-params-example: '?dispute_id=bVTprrwk0gygTLZ96VX1oB'
      properties:
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
      example: {}
    ListDisputeEvidenceResponse:
      type: object
      description: Defines the fields in a `ListDisputeEvidence` response.
      x-release-status: PUBLIC
      properties:
        evidence:
          type: array
          items:
            $ref: '#/components/schemas/DisputeEvidence'
          description: The list of evidence previously uploaded to the specified dispute.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request.

            If unset, this is the final response. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        evidence:
          - dispute_id: bVTprrwk0gygTLZ96VX1oB
            evidence_file:
              filename: customer-interaction
              filetype: JPG
            evidence_type: CARDHOLDER_COMMUNICATION
            id: CpfnkwGselCwS8QFvxN6
            uploaded_at: '2022-05-10T15:57:13.802Z'
          - dispute_id: bVTprrwk0gygTLZ96VX1oB
            evidence_file:
              filename: ''
              filetype: ''
            evidence_type: REBUTTAL_EXPLANATION
            id: TOomLInj6iWmP3N8qfCXrB
            uploaded_at: '2022-05-18T16:01:10.000Z'
    ListDisputesRequest:
      type: object
      description: Defines the request parameters for the `ListDisputes` endpoint.
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        states:
          type: array
          items:
            $ref: '#/components/schemas/DisputeState'
          description: >-
            The dispute states used to filter the result. If not specified, the
            endpoint returns all disputes.

            See [DisputeState](#type-disputestate) for possible values
          nullable: true
        location_id:
          type: string
          description: >-
            The ID of the location for which to return a list of disputes.

            If not specified, the endpoint returns disputes associated with all
            locations.
          minLength: 1
          maxLength: 40
          nullable: true
      example: {}
    ListDisputesResponse:
      type: object
      description: Defines fields in a `ListDisputes` response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        disputes:
          type: array
          items:
            $ref: '#/components/schemas/Dispute'
          description: The list of disputes.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request.

            If unset, this is the final response. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        cursor: G1aSTRm48CLjJsg6Sg3hQN1b1OMaoVuG
        disputes:
          - amount_money:
              amount: 2500
              currency: USD
            brand_dispute_id: '100000809947'
            card_brand: VISA
            created_at: '2022-06-29T18:45:22.265Z'
            disputed_payment:
              payment_id: zhyh1ch64kRBrrlfVhwjCEjZWzNZY
            due_at: '2022-07-13T00:00:00.000Z'
            id: XDgyFu7yo1E2S5lQGGpYn
            location_id: L1HN3ZMQK64X9
            reason: NO_KNOWLEDGE
            reported_at: '2022-06-29T00:00:00.000Z'
            state: ACCEPTED
            updated_at: '2022-07-07T19:14:42.650Z'
            version: 2
          - amount_money:
              amount: 2209
              currency: USD
            brand_dispute_id: r5Of6YaGT7AdeRaVoAGCJw
            card_brand: VISA
            created_at: '2022-04-29T18:45:22.265Z'
            disputed_payment:
              payment_id: zhyh1ch64kRBrrlfVhwjCEjZWzNZY
            due_at: '2022-05-13T00:00:00.000Z'
            id: jLGg7aXC7lvKPr9PISt0T
            location_id: 18YC4JDH91E1H
            reason: NOT_AS_DESCRIBED
            reported_at: '2022-04-29T00:00:00.000Z'
            state: EVIDENCE_REQUIRED
            updated_at: '2022-04-29T18:45:22.265Z'
            version: 1
    ListEmployeeWagesRequest:
      type: object
      description: A request for a set of `EmployeeWage` objects.
      x-release-status: DEPRECATED
      x-params-example: >-
        ?employee_id=33fJchumvVdJwxV0H6L9&limit=4&cursor=s4R0Z6ecFTzTC4jz8sUDBQTudX3KE313OT9fCt3VUgsXM4sMgED
      properties:
        employee_id:
          type: string
          description: >-
            Filter the returned wages to only those that are associated with the
            specified employee.
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of `EmployeeWage` results to return per page. The
            number can range between

            1 and 200. The default is 200.
          minimum: 1
          maximum: 200
          nullable: true
        cursor:
          type: string
          description: A pointer to the next page of `EmployeeWage` results to fetch.
          nullable: true
    ListEmployeeWagesResponse:
      type: object
      description: >-
        The response to a request for a set of `EmployeeWage` objects. The
        response contains

        a set of `EmployeeWage` objects.
      x-release-status: DEPRECATED
      properties:
        employee_wages:
          type: array
          items:
            $ref: '#/components/schemas/EmployeeWage'
          description: A page of `EmployeeWage` results.
        cursor:
          type: string
          description: |-
            The value supplied in the subsequent request to fetch the next page
            of `EmployeeWage` results.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        cursor: 2fofTniCgT0yIPAq26kmk0YyFQJZfbWkh73OOnlTHmTAx13NgED
        employee_wages:
          - employee_id: 33fJchumvVdJwxV0H6L9
            hourly_rate:
              amount: 3250
              currency: USD
            id: pXS3qCv7BERPnEGedM4S8mhm
            title: Manager
          - employee_id: 33fJchumvVdJwxV0H6L9
            hourly_rate:
              amount: 2600
              currency: USD
            id: rZduCkzYDUVL3ovh1sQgbue6
            title: Cook
          - employee_id: 33fJchumvVdJwxV0H6L9
            hourly_rate:
              amount: 1600
              currency: USD
            id: FxLbs5KpPUHa8wyt5ctjubDX
            title: Barista
          - employee_id: 33fJchumvVdJwxV0H6L9
            hourly_rate:
              amount: 1700
              currency: USD
            id: vD1wCgijMDR3cX5TPnu7VXto
            title: Cashier
    ListEmployeesRequest:
      type: object
      x-release-status: DEPRECATED
      properties:
        location_id:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/EmployeeStatus'
          description: |-
            Specifies the EmployeeStatus to filter the employee by.
            See [EmployeeStatus](#type-employeestatus) for possible values
          nullable: true
        limit:
          type: integer
          description: The number of employees to be returned on each page.
          nullable: true
        cursor:
          type: string
          description: The token required to retrieve the specified page of results.
          nullable: true
    ListEmployeesResponse:
      type: object
      x-release-status: DEPRECATED
      properties:
        employees:
          type: array
          items:
            $ref: '#/components/schemas/Employee'
        cursor:
          type: string
          description: The token to be used to retrieve the next page of results.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
    ListEventTypesRequest:
      type: object
      description: Lists all event types that can be subscribed to.
      x-release-status: BETA
      properties:
        api_version:
          type: string
          description: >-
            The API version for which to list event types. Setting this field
            overrides the default version used by the application.
          nullable: true
    ListEventTypesResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [ListEventTypes](api-endpoint:Events-ListEventTypes)
        endpoint.


        Note: if there are errors processing the request, the event types field
        will not be

        present.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        event_types:
          type: array
          items:
            type: string
          description: The list of event types.
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/EventTypeMetadata'
          description: >-
            Contains the metadata of an event type. For more information, see
            [EventTypeMetadata](entity:EventTypeMetadata).
      example:
        event_types:
          - inventory.count.updated
        metadata:
          - api_version_introduced: '2018-07-12'
            event_type: inventory.count.updated
            release_status: PUBLIC
    ListGiftCardActivitiesRequest:
      type: object
      description: >-
        Returns a list of gift card activities. You can optionally specify a
        filter to retrieve a

        subset of activites.
      x-release-status: PUBLIC
      properties:
        gift_card_id:
          type: string
          description: >-
            If a gift card ID is provided, the endpoint returns activities
            related 

            to the specified gift card. Otherwise, the endpoint returns all gift
            card activities for 

            the seller.
          maxLength: 50
          nullable: true
        type:
          type: string
          description: >-
            If a [type](entity:GiftCardActivityType) is provided, the endpoint
            returns gift card activities of the specified type. 

            Otherwise, the endpoint returns all types of gift card activities.
          nullable: true
        location_id:
          type: string
          description: >-
            If a location ID is provided, the endpoint returns gift card
            activities for the specified location. 

            Otherwise, the endpoint returns gift card activities for all
            locations.
          nullable: true
        begin_time:
          type: string
          description: >-
            The timestamp for the beginning of the reporting period, in RFC 3339
            format.

            This start time is inclusive. The default value is the current time
            minus one year.
          nullable: true
        end_time:
          type: string
          description: >-
            The timestamp for the end of the reporting period, in RFC 3339
            format.

            This end time is inclusive. The default value is the current time.
          nullable: true
        limit:
          type: integer
          description: >-
            If a limit is provided, the endpoint returns the specified number 

            of results (or fewer) per page. The maximum value is 100. The
            default value is 50.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          minimum: 1
          maximum: 100
          nullable: true
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            If a cursor is not provided, the endpoint returns the first page of
            the results.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          nullable: true
        sort_order:
          type: string
          description: >-
            The order in which the endpoint returns the activities, based on
            `created_at`.

            - `ASC` - Oldest to newest.

            - `DESC` - Newest to oldest (default).
          nullable: true
      example: {}
    ListGiftCardActivitiesResponse:
      type: object
      description: >-
        A response that contains a list of `GiftCardActivity` objects. If the
        request resulted in errors, 

        the response contains a set of `Error` objects.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        gift_card_activities:
          type: array
          items:
            $ref: '#/components/schemas/GiftCardActivity'
          description: >-
            The requested gift card activities or an empty object if none are
            found.
        cursor:
          type: string
          description: >-
            When a response is truncated, it includes a cursor that you can use
            in a

            subsequent request to retrieve the next set of activities. If a
            cursor is not present, this is

            the final response.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
      example:
        gift_card_activities:
          - created_at: '2021-06-02T22:26:38.000Z'
            gift_card_balance_money:
              amount: 700
              currency: USD
            gift_card_gan: '7783320002929081'
            gift_card_id: gftc:6d55a72470d940c6ba09c0ab8ad08d20
            id: gcact_897698f894b44b3db46c6147e26a0e19
            location_id: 81FN9BNFZTKS4
            payment_id: dEv2eksNPy6GqdYiLe4ZBNk6HqXZY
            redeem_activity_details:
              amount_money:
                amount: 300
                currency: USD
            status: COMPLETED
            type: REDEEM
          - activate_activity_details:
              amount_money:
                amount: 1000
                currency: USD
              line_item_uid: eIWl7X0nMuO9Ewbh0ChIx
              order_id: jJNGHm4gLI6XkFbwtiSLqK72KkAZY
            created_at: '2021-05-20T22:26:54.000Z'
            gift_card_balance_money:
              amount: 1000
              currency: USD
            gift_card_gan: '7783320002929081'
            gift_card_id: gftc:6d55a72470d940c6ba09c0ab8ad08d20
            id: gcact_b968ebfc7d46437b945be7b9e09123b4
            location_id: 81FN9BNFZTKS4
            type: ACTIVATE
    ListGiftCardsRequest:
      type: object
      description: >-
        A request to list gift cards. You can optionally specify a filter to
        retrieve a subset of 

        gift cards.
      x-release-status: PUBLIC
      x-params-example: '?type=DIGITAL&state=ACTIVE&cursor=Jj0rA9-rrDW5k-PsorOq-m4BiGf'
      properties:
        type:
          type: string
          description: >-
            If a [type](entity:GiftCardType) is provided, the endpoint returns
            gift cards of the specified type.

            Otherwise, the endpoint returns gift cards of all types.
          nullable: true
        state:
          type: string
          description: >-
            If a [state](entity:GiftCardStatus) is provided, the endpoint
            returns the gift cards in the specified state.

            Otherwise, the endpoint returns the gift cards of all states.
          nullable: true
        limit:
          type: integer
          description: >-
            If a limit is provided, the endpoint returns only the specified
            number of results per page.

            The maximum value is 200. The default value is 30.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          minimum: 1
          maximum: 200
          nullable: true
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            If a cursor is not provided, the endpoint returns the first page of
            the results. 

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          nullable: true
        customer_id:
          type: string
          description: >-
            If a customer ID is provided, the endpoint returns only the gift
            cards linked to the specified customer.
          maxLength: 191
          nullable: true
    ListGiftCardsResponse:
      type: object
      description: >-
        A response that contains a list of `GiftCard` objects. If the request
        resulted in errors, 

        the response contains a set of `Error` objects.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        gift_cards:
          type: array
          items:
            $ref: '#/components/schemas/GiftCard'
          description: The requested gift cards or an empty object if none are found.
        cursor:
          type: string
          description: >-
            When a response is truncated, it includes a cursor that you can use
            in a

            subsequent request to retrieve the next set of gift cards. If a
            cursor is not present, this is

            the final response.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
      example:
        cursor: JbFmyvUpaNKsfC1hoLSA4WlqkgkZXTWeKuStajR5BkP7OE0ETAbeWSi6U6u7sH
        gift_cards:
          - balance_money:
              amount: 3900
              currency: USD
            created_at: '2021-06-09T22:26:54.000Z'
            gan: '7783320008524605'
            gan_source: SQUARE
            id: gftc:00113070ba5745f0b2377c1b9570cb03
            state: ACTIVE
            type: DIGITAL
          - balance_money:
              amount: 2000
              currency: USD
            created_at: '2021-05-20T22:26:54.000Z'
            gan: '7783320002692465'
            gan_source: SQUARE
            id: gftc:00128a12725b41e58e0de1d20497a9dd
            state: ACTIVE
            type: DIGITAL
    ListInvoicesRequest:
      type: object
      description: Describes a `ListInvoice` request.
      x-release-status: PUBLIC
      x-params-example: '?location_id=ES0RJRZYEC39A&limit=2'
      required:
        - location_id
      properties:
        location_id:
          type: string
          description: The ID of the location for which to list invoices.
          minLength: 1
          maxLength: 255
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint. 

            Provide this cursor to retrieve the next set of results for your
            original query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of invoices to return (200 is the maximum
            `limit`). 

            If not provided, the server uses a default limit of 100 invoices.
          nullable: true
    ListInvoicesResponse:
      type: object
      description: Describes a `ListInvoice` response.
      x-release-status: PUBLIC
      properties:
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/Invoice'
          description: The invoices retrieved.
        cursor:
          type: string
          description: >-
            When a response is truncated, it includes a cursor that you can use
            in a 

            subsequent request to retrieve the next set of invoices. If empty,
            this is the final 

            response. 

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example:
        cursor: ChoIDhIWVm54ZVRhLXhySFBOejBBM2xJb2daUQoFCI4IGAE
        invoices:
          - accepted_payment_methods:
              bank_account: false
              buy_now_pay_later: false
              card: true
              cash_app_pay: false
              square_gift_card: false
            attachments:
              - description: Service contract
                filename: file.jpg
                filesize: 102705
                hash: 273ee02cb6f5f8a3a8ca23604930dd53
                id: inva:0-3bB9ZuDHiziThQhuC4fwWt
                mime_type: image/jpeg
                uploaded_at: '2030-01-13T21:24:10Z'
            created_at: '2030-01-13T17:45:13Z'
            custom_fields:
              - label: Event Reference Number
                placement: ABOVE_LINE_ITEMS
                value: 'Ref. #1234'
              - label: Terms of Service
                placement: BELOW_LINE_ITEMS
                value: The terms of service are...
            delivery_method: EMAIL
            description: We appreciate your business!
            id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
            invoice_number: inv-100
            location_id: ES0RJRZYEC39A
            order_id: CAISENgvlJ6jLWAzERDzjyHVybY
            payment_requests:
              - automatic_payment_source: NONE
                computed_amount_money:
                  amount: 10000
                  currency: USD
                due_date: '2030-01-24'
                reminders:
                  - message: Your invoice is due tomorrow
                    relative_scheduled_days: -1
                    status: PENDING
                    uid: beebd363-e47f-4075-8785-c235aaa7df11
                request_type: BALANCE
                tipping_enabled: true
                total_completed_amount_money:
                  amount: 0
                  currency: USD
                uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355
            primary_recipient:
              customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4
              email_address: Amelia.Earhart@example.com
              family_name: Earhart
              given_name: Amelia
              phone_number: 1-212-555-4240
            sale_or_service_date: '2030-01-24'
            scheduled_at: '2030-01-13T10:00:00Z'
            status: DRAFT
            store_payment_method_enabled: false
            timezone: America/Los_Angeles
            title: Event Planning Services
            updated_at: '2030-01-13T21:24:10Z'
            version: 1
          - accepted_payment_methods:
              bank_account: false
              buy_now_pay_later: false
              card: true
              cash_app_pay: false
              square_gift_card: true
            created_at: '2021-01-23T15:29:12Z'
            delivery_method: EMAIL
            id: inv:0-ChC366qAfskpGrBI_1bozs9mEA3
            invoice_number: inv-455
            location_id: ES0RJRZYEC39A
            next_payment_amount_money:
              amount: 3000
              currency: USD
            order_id: a65jnS8NXbfprvGJzY9F4fQTuaB
            payment_requests:
              - automatic_payment_source: CARD_ON_FILE
                card_id: ccof:IkWfpLj4tNHMyFii3GB
                computed_amount_money:
                  amount: 1000
                  currency: USD
                due_date: '2021-01-23'
                percentage_requested: '25'
                request_type: DEPOSIT
                tipping_enabled: false
                total_completed_amount_money:
                  amount: 1000
                  currency: USD
                uid: 66c3bdfd-5090-4ff9-a8a0-c1e1a2ffa176
              - automatic_payment_source: CARD_ON_FILE
                card_id: ccof:IkWfpLj4tNHMyFii3GB
                computed_amount_money:
                  amount: 3000
                  currency: USD
                due_date: '2021-06-15'
                request_type: BALANCE
                tipping_enabled: false
                total_completed_amount_money:
                  amount: 0
                  currency: USD
                uid: 120c5e18-4f80-4f6b-b159-774cb9bf8f99
            primary_recipient:
              customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4
              email_address: Amelia.Earhart@example.com
              family_name: Earhart
              given_name: Amelia
              phone_number: 1-212-555-4240
            public_url: https://squareup.com/pay-invoice/h9sfsfTGTSnYEhISUDBhEQ
            sale_or_service_date: '2030-01-24'
            status: PARTIALLY_PAID
            store_payment_method_enabled: false
            timezone: America/Los_Angeles
            updated_at: '2021-01-23T15:29:56Z'
            version: 3
    ListJobsRequest:
      type: object
      description: Represents a [ListJobs](api-endpoint:Team-ListJobs) request.
      x-release-status: BETA
      properties:
        cursor:
          type: string
          description: >-
            The pagination cursor returned by the previous call to this
            endpoint. Provide this

            cursor to retrieve the next page of results for your original
            request. For more information,

            see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
      example: {}
    ListJobsResponse:
      type: object
      description: >-
        Represents a [ListJobs](api-endpoint:Team-ListJobs) response. Either
        `jobs` or `errors`

        is present in the response. If additional results are available, the
        `cursor` field is also present.
      x-release-status: BETA
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/Job'
          description: The retrieved jobs. A single paged response contains up to 100 jobs.
        cursor:
          type: string
          description: >-
            An opaque cursor used to retrieve the next page of results. This
            field is present only

            if the request succeeded and additional results are available. For
            more information, see

            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: The errors that occurred during the request.
      example:
        jobs:
          - created_at: '2021-06-11T22:55:45Z'
            id: VDNpRv8da51NU8qZFC5zDWpF
            is_tip_eligible: true
            title: Cashier
            updated_at: '2021-06-11T22:55:45Z'
            version: 2
          - created_at: '2021-06-11T22:55:45Z'
            id: FjS8x95cqHiMenw4f1NAUH4P
            is_tip_eligible: false
            title: Chef
            updated_at: '2021-06-11T22:55:45Z'
            version: 1
    ListLocationBookingProfilesRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        limit:
          type: integer
          description: The maximum number of results to return in a paged response.
          minimum: 1
          maximum: 100
          nullable: true
        cursor:
          type: string
          description: >-
            The pagination cursor from the preceding response to return the next
            page of the results. Do not set this when retrieving the first page
            of the results.
          maxLength: 65536
          nullable: true
    ListLocationBookingProfilesResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        location_booking_profiles:
          type: array
          items:
            $ref: '#/components/schemas/LocationBookingProfile'
          description: The list of a seller's location booking profiles.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in the subsequent request to get
            the next page of the results. Stop retrieving the next page of the
            results when the cursor is not set.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
      example:
        errors: []
        location_booking_profiles:
          - booking_site_url: https://squareup.com/book/LY6WNBPVM6VGV/testbusiness
            location_id: LY6WNBPVM6VGV
            online_booking_enabled: true
          - location_id: PYTRNBPVMJUPV
            online_booking_enabled: false
    ListLocationCustomAttributeDefinitionsRequest:
      type: object
      description: >-
        Represents a
        [ListLocationCustomAttributeDefinitions](api-endpoint:LocationCustomAttributes-ListLocationCustomAttributeDefinitions)
        request.
      x-release-status: BETA
      x-params-example: '?limit=2'
      properties:
        visibility_filter:
          $ref: '#/components/schemas/VisibilityFilter'
          description: >-
            Filters the `CustomAttributeDefinition` results by their
            `visibility` values.

            See [VisibilityFilter](#type-visibilityfilter) for possible values
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          minimum: 1
          maximum: 100
          nullable: true
        cursor:
          type: string
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
    ListLocationCustomAttributeDefinitionsResponse:
      type: object
      description: >-
        Represents a
        [ListLocationCustomAttributeDefinitions](api-endpoint:LocationCustomAttributes-ListLocationCustomAttributeDefinitions)
        response.

        Either `custom_attribute_definitions`, an empty object, or `errors` is
        present in the response.

        If additional results are available, the `cursor` field is also present
        along with `custom_attribute_definitions`.
      x-release-status: BETA
      properties:
        custom_attribute_definitions:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The retrieved custom attribute definitions. If no custom attribute
            definitions are found,

            Square returns an empty object (`{}`).
        cursor:
          type: string
          description: >-
            The cursor to provide in your next call to this endpoint to retrieve
            the next page of

            results for your original request. This field is present only if the
            request succeeded and

            additional results are available. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        cursor: >-
          ImfNzWVSiAYyiAR4gEcxDJ75KZAOSjX8H2BVHUTR0ofCtp4SdYvrUKbwYY2aCH2WqZ2FsfAuylEVUlTfaINg3ecIlFpP9Y5Ie66w9NSg9nqdI5fCJ6qdH2s0za5m2plFonsjIuFaoN89j78ROUwuSOzD6mFZPcJHhJ0CxEKc0SBH
        custom_attribute_definitions:
          - created_at: '2022-12-02T19:50:21.832Z'
            description: Location's phone number
            key: phone-number
            name: phone number
            schema:
              $ref: >-
                https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.PhoneNumber
            updated_at: '2022-12-02T19:50:21.832Z'
            version: 1
            visibility: VISIBILITY_READ_ONLY
          - created_at: '2022-12-02T19:06:36.559Z'
            description: Bestselling item at location
            key: bestseller
            name: Bestseller
            schema:
              $ref: >-
                https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
            updated_at: '2022-12-03T10:17:52.341Z'
            version: 4
            visibility: VISIBILITY_READ_WRITE_VALUES
    ListLocationCustomAttributesRequest:
      type: object
      description: >-
        Represents a
        [ListLocationCustomAttributes](api-endpoint:LocationCustomAttributes-ListLocationCustomAttributes)
        request.
      x-release-status: BETA
      x-params-example: '?location_id=L0TBCBTB7P8RQ'
      properties:
        visibility_filter:
          $ref: '#/components/schemas/VisibilityFilter'
          description: >-
            Filters the `CustomAttributeDefinition` results by their
            `visibility` values.

            See [VisibilityFilter](#type-visibilityfilter) for possible values
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          minimum: 1
          maximum: 100
          nullable: true
        cursor:
          type: string
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request. For more

            information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        with_definitions:
          type: boolean
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of each

            custom attribute. Set this parameter to `true` to get the name and
            description of each custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          nullable: true
    ListLocationCustomAttributesResponse:
      type: object
      description: >-
        Represents a
        [ListLocationCustomAttributes](api-endpoint:LocationCustomAttributes-ListLocationCustomAttributes)
        response.

        Either `custom_attributes`, an empty object, or `errors` is present in
        the response. If additional

        results are available, the `cursor` field is also present along with
        `custom_attributes`.
      x-release-status: BETA
      properties:
        custom_attributes:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The retrieved custom attributes. If `with_definitions` was set to
            `true` in the request,

            the custom attribute definition is returned in the `definition`
            field of each custom attribute.

            If no custom attributes are found, Square returns an empty object
            (`{}`).
        cursor:
          type: string
          description: >-
            The cursor to use in your next call to this endpoint to retrieve the
            next page of results

            for your original request. This field is present only if the request
            succeeded and additional

            results are available. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attributes:
          - created_at: '2022-12-12T18:13:03.745Z'
            key: phone-number
            updated_at: '2022-12-12T18:13:03.745Z'
            value: '+12223334444'
            version: 1
            visibility: VISIBILITY_READ_WRITE_VALUES
          - created_at: '2022-12-12T19:27:57.975Z'
            key: bestseller
            updated_at: '2022-12-12T19:27:57.975Z'
            value: hot cocoa
            version: 1
            visibility: VISIBILITY_READ_WRITE_VALUES
    ListLocationsRequest:
      type: object
      description: |-
        Defines the fields that are included in requests to the
        [ListLocations](api-endpoint:Locations-ListLocations) endpoint.
      x-release-status: PUBLIC
      properties: {}
    ListLocationsResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of a request

        to the [ListLocations](api-endpoint:Locations-ListLocations) endpoint.


        Either `errors` or `locations` is present in a given response (never
        both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
          description: The business locations.
      example:
        locations:
          - address:
              address_line_1: 123 Main St
              administrative_district_level_1: CA
              country: US
              locality: San Francisco
              postal_code: '94114'
            business_name: Jet Fuel Coffee
            capabilities:
              - CREDIT_CARD_PROCESSING
            country: US
            created_at: '2016-09-19T17:33:12Z'
            currency: USD
            id: 18YC4JDH91E1H
            language_code: en-US
            merchant_id: 3MYCJG5GVYQ8Q
            name: Grant Park
            phone_number: +1 650-354-7217
            status: ACTIVE
            timezone: America/Los_Angeles
          - address:
              address_line_1: 1234 Peachtree St. NE
              administrative_district_level_1: GA
              locality: Atlanta
              postal_code: '30309'
            business_name: Jet Fuel Coffee
            capabilities:
              - CREDIT_CARD_PROCESSING
            coordinates:
              latitude: 33.7889
              longitude: -84.3841
            country: US
            created_at: '2022-02-19T17:58:25Z'
            currency: USD
            description: Midtown Atlanta store
            id: 3Z4V4WHQK64X9
            language_code: en-US
            mcc: '7299'
            merchant_id: 3MYCJG5GVYQ8Q
            name: Midtown
            status: ACTIVE
            timezone: America/New_York
            type: PHYSICAL
    ListLoyaltyProgramsRequest:
      type: object
      description: A request to list `LoyaltyProgram`.
      x-release-status: DEPRECATED
      properties: {}
      example: {}
    ListLoyaltyProgramsResponse:
      type: object
      description: A response that contains all loyalty programs.
      x-release-status: DEPRECATED
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        programs:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyProgram'
          description: A list of `LoyaltyProgram` for the merchant.
      example:
        programs:
          - accrual_rules:
              - accrual_type: SPEND
                points: 1
                spend_data:
                  amount_money:
                    amount: 100
                    currency: USD
                  excluded_category_ids:
                    - 7ZERJKO5PVYXCVUHV2JCZ2UG
                    - FQKAOJE5C4FIMF5A2URMLW6V
                  excluded_item_variation_ids:
                    - CBZXBUVVTYUBZGQO44RHMR6B
                    - EDILT24Z2NISEXDKGY6HP7XV
                  tax_mode: BEFORE_TAX
            created_at: '2020-04-20T16:55:11Z'
            id: d619f755-2d17-41f3-990d-c04ecedd64dd
            location_ids:
              - P034NEENMD09F
            reward_tiers:
              - created_at: '2020-04-20T16:55:11Z'
                definition:
                  discount_type: FIXED_PERCENTAGE
                  percentage_discount: '10'
                  scope: ORDER
                id: e1b39225-9da5-43d1-a5db-782cdd8ad94f
                name: 10% off entire sale
                points: 10
                pricing_rule_reference:
                  catalog_version: '1605486402527'
                  object_id: 74C4JSHESNLTB2A7ITO5HO6F
            status: ACTIVE
            terminology:
              one: Point
              other: Points
            updated_at: '2020-05-01T02:00:02Z'
    ListLoyaltyPromotionsRequest:
      type: object
      description: >-
        Represents a
        [ListLoyaltyPromotions](api-endpoint:Loyalty-ListLoyaltyPromotions)
        request.
      x-release-status: PUBLIC
      x-params-example: '?program_id=d619f755-2d17-41f3-990d-c04ecedd64dd'
      properties:
        status:
          $ref: '#/components/schemas/LoyaltyPromotionStatus'
          description: >-
            The status to filter the results by. If a status is provided, only
            loyalty promotions

            with the specified status are returned. Otherwise, all loyalty
            promotions associated with

            the loyalty program are returned.

            See [LoyaltyPromotionStatus](#type-loyaltypromotionstatus) for
            possible values
          readOnly: true
        cursor:
          type: string
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single paged response.

            The minimum value is 1 and the maximum value is 30. The default
            value is 30.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          minimum: 1
          maximum: 30
          nullable: true
      example: {}
    ListLoyaltyPromotionsResponse:
      type: object
      description: >-
        Represents a
        [ListLoyaltyPromotions](api-endpoint:Loyalty-ListLoyaltyPromotions)
        response.

        One of `loyalty_promotions`, an empty object, or `errors` is present in
        the response.

        If additional results are available, the `cursor` field is also present
        along with `loyalty_promotions`.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        loyalty_promotions:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyPromotion'
          description: The retrieved loyalty promotions.
        cursor:
          type: string
          description: >-
            The cursor to use in your next call to this endpoint to retrieve the
            next page of results

            for your original request. This field is present only if the request
            succeeded and additional

            results are available. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        loyalty_promotions:
          - available_time:
              start_date: '2022-08-16'
              time_periods:
                - |-
                  BEGIN:VEVENT
                  DTSTART:20220816T160000
                  DURATION:PT2H
                  RRULE:FREQ=WEEKLY;BYDAY=TU
                  END:VEVENT
            created_at: '2022-08-16T08:38:54Z'
            id: loypromo_f0f9b849-725e-378d-b810-511237e07b67
            incentive:
              points_multiplier_data:
                multiplier: '3.000'
                points_multiplier: 3
              type: POINTS_MULTIPLIER
            loyalty_program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
            name: Tuesday Happy Hour Promo
            qualifying_item_variation_ids:
              - CJ3RYL56ITAKMD4VRCM7XERS
              - AT3RYLR3TUA9C34VRCB7X5RR
            status: ACTIVE
            trigger_limit:
              interval: DAY
              times: 1
            updated_at: '2022-08-16T08:38:54Z'
          - available_time:
              end_date: '2022-08-01'
              start_date: '2022-07-01'
              time_periods:
                - |-
                  BEGIN:VEVENT
                  DTSTART:20220704T090000
                  DURATION:PT8H
                  RRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=MO
                  END:VEVENT
                - |-
                  BEGIN:VEVENT
                  DTSTART:20220705T090000
                  DURATION:PT8H
                  RRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=TU
                  END:VEVENT
                - |-
                  BEGIN:VEVENT
                  DTSTART:20220706T090000
                  DURATION:PT8H
                  RRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=WE
                  END:VEVENT
                - |-
                  BEGIN:VEVENT
                  DTSTART:20220707T090000
                  DURATION:PT8H
                  RRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=TH
                  END:VEVENT
                - |-
                  BEGIN:VEVENT
                  DTSTART:20220701T090000
                  DURATION:PT8H
                  RRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=FR
                  END:VEVENT
            created_at: '2022-06-27T15:37:38Z'
            id: loypromo_e696f057-2286-35ff-8108-132241328106
            incentive:
              points_multiplier_data:
                multiplier: '2.000'
                points_multiplier: 2
              type: POINTS_MULTIPLIER
            loyalty_program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
            minimum_spend_amount_money:
              amount: 2000
              currency: USD
            name: July Special
            qualifying_category_ids:
              - XTQPYLR3IIU9C44VRCB3XD12
            status: ENDED
            trigger_limit:
              interval: ALL_TIME
              times: 5
            updated_at: '2022-06-27T15:37:38Z'
    ListMerchantCustomAttributeDefinitionsRequest:
      type: object
      description: >-
        Represents a
        [ListMerchantCustomAttributeDefinitions](api-endpoint:MerchantCustomAttributes-ListMerchantCustomAttributeDefinitions)
        request.
      x-release-status: BETA
      x-params-example: '?limit=2'
      properties:
        visibility_filter:
          $ref: '#/components/schemas/VisibilityFilter'
          description: >-
            Filters the `CustomAttributeDefinition` results by their
            `visibility` values.

            See [VisibilityFilter](#type-visibilityfilter) for possible values
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          minimum: 1
          maximum: 100
          nullable: true
        cursor:
          type: string
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
    ListMerchantCustomAttributeDefinitionsResponse:
      type: object
      description: >-
        Represents a
        [ListMerchantCustomAttributeDefinitions](api-endpoint:MerchantCustomAttributes-ListMerchantCustomAttributeDefinitions)
        response.

        Either `custom_attribute_definitions`, an empty object, or `errors` is
        present in the response.

        If additional results are available, the `cursor` field is also present
        along with `custom_attribute_definitions`.
      x-release-status: BETA
      properties:
        custom_attribute_definitions:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The retrieved custom attribute definitions. If no custom attribute
            definitions are found,

            Square returns an empty object (`{}`).
        cursor:
          type: string
          description: >-
            The cursor to provide in your next call to this endpoint to retrieve
            the next page of

            results for your original request. This field is present only if the
            request succeeded and

            additional results are available. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        cursor: >-
          ImfNzWVSiAYyiAR4gEcxDJ75KZAOSjX8H2BVHUTR0ofCtp4SdYvrUKbwYY2aCH2WqZ2FsfAuylEVUlTfaINg3ecIlFpP9Y5Ie66w9NSg9nqdI5fCJ6qdH2s0za5m2plFonsjIuFaoN89j78ROUwuSOzD6mFZPcJHhJ0CxEKc0SBH
        custom_attribute_definitions:
          - created_at: '2023-05-05T16:50:21.832Z'
            description: >-
              Whether the merchant has seen the tutorial screen for using the
              app.
            key: has_seen_tutorial
            name: NAME
            schema:
              $ref: >-
                https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Boolean
            updated_at: '2023-05-05T16:50:21.832Z'
            version: 1
            visibility: VISIBILITY_READ_WRITE_VALUES
          - created_at: '2023-05-05T19:06:36.559Z'
            description: This is the other name this merchant goes by.
            key: alternative_seller_name
            name: Alternative Merchant Name
            schema:
              $ref: >-
                https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
            updated_at: '2023-05-05T10:17:52.341Z'
            version: 4
            visibility: VISIBILITY_READ_ONLY
    ListMerchantCustomAttributesRequest:
      type: object
      description: >-
        Represents a
        [ListMerchantCustomAttributes](api-endpoint:MerchantCustomAttributes-ListMerchantCustomAttributes)
        request.
      x-release-status: BETA
      x-params-example: '?merchant_id=DM7VKY8Q63GNP'
      properties:
        visibility_filter:
          $ref: '#/components/schemas/VisibilityFilter'
          description: >-
            Filters the `CustomAttributeDefinition` results by their
            `visibility` values.

            See [VisibilityFilter](#type-visibilityfilter) for possible values
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          minimum: 1
          maximum: 100
          nullable: true
        cursor:
          type: string
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request. For more

            information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        with_definitions:
          type: boolean
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of each

            custom attribute. Set this parameter to `true` to get the name and
            description of each custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          nullable: true
    ListMerchantCustomAttributesResponse:
      type: object
      description: >-
        Represents a
        [ListMerchantCustomAttributes](api-endpoint:MerchantCustomAttributes-ListMerchantCustomAttributes)
        response.

        Either `custom_attributes`, an empty object, or `errors` is present in
        the response. If additional

        results are available, the `cursor` field is also present along with
        `custom_attributes`.
      x-release-status: BETA
      properties:
        custom_attributes:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The retrieved custom attributes. If `with_definitions` was set to
            `true` in the request,

            the custom attribute definition is returned in the `definition`
            field of each custom attribute.

            If no custom attributes are found, Square returns an empty object
            (`{}`).
        cursor:
          type: string
          description: >-
            The cursor to use in your next call to this endpoint to retrieve the
            next page of results

            for your original request. This field is present only if the request
            succeeded and additional

            results are available. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attributes:
          - created_at: '2023-05-05T18:13:03.745Z'
            key: has_seen_tutorial
            updated_at: '2023-05-05T18:13:03.745Z'
            value: true
            version: 1
            visibility: VISIBILITY_READ_WRITE_VALUES
          - created_at: '2023-05-05T19:27:57.975Z'
            key: alternative_seller_name
            updated_at: '2023-05-05T19:27:57.975Z'
            value: Ultimate Sneaker Store
            version: 1
            visibility: VISIBILITY_READ_ONLY
    ListMerchantsRequest:
      type: object
      description: >-
        Request object for the
        [ListMerchant](api-endpoint:Merchants-ListMerchants) endpoint.
      x-release-status: PUBLIC
      properties:
        cursor:
          type: integer
          description: The cursor generated by the previous response.
          nullable: true
    ListMerchantsResponse:
      type: object
      description: >-
        The response object returned by the
        [ListMerchant](api-endpoint:Merchants-ListMerchants) endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        merchant:
          type: array
          items:
            $ref: '#/components/schemas/Merchant'
          description: The requested `Merchant` entities.
        cursor:
          type: integer
          description: >-
            If the  response is truncated, the cursor to use in next  request to
            fetch next set of objects.
      example:
        merchant:
          - business_name: Apple A Day
            country: US
            created_at: '2021-12-10T19:25:52.484Z'
            currency: USD
            id: DM7VKY8Q63GNP
            language_code: en-US
            main_location_id: 9A65CGC72ZQG1
            status: ACTIVE
    ListOrderCustomAttributeDefinitionsRequest:
      type: object
      description: Represents a list request for order custom attribute definitions.
      x-release-status: BETA
      x-params-example: '?limit=4'
      properties:
        visibility_filter:
          $ref: '#/components/schemas/VisibilityFilter'
          description: >-
            Requests that all of the custom attributes be returned, or only
            those that are read-only or read-write.

            See [VisibilityFilter](#type-visibilityfilter) for possible values
          nullable: true
        cursor:
          type: string
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint. 

            Provide this cursor to retrieve the next page of results for your
            original request. 

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          minLength: 1
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory. 

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100. 

            The default value is 20.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          minimum: 1
          maximum: 100
          nullable: true
    ListOrderCustomAttributeDefinitionsResponse:
      type: object
      description: Represents a response from listing order custom attribute definitions.
      x-release-status: BETA
      required:
        - custom_attribute_definitions
      properties:
        custom_attribute_definitions:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The retrieved custom attribute definitions. If no custom attribute
            definitions are found, Square returns an empty object (`{}`).
        cursor:
          type: string
          description: >-
            The cursor to provide in your next call to this endpoint to retrieve
            the next page of results for your original request. 

            This field is present only if the request succeeded and additional
            results are available.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          minLength: 1
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definitions:
          - created_at: '2022-11-16T18:03:44.051Z'
            description: The number of people seated at a table
            key: cover-count
            name: Cover count
            schema:
              $ref: >-
                https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number
            updated_at: '2022-11-16T18:03:44.051Z'
            version: 1
            visibility: VISIBILITY_READ_WRITE_VALUES
          - created_at: '2022-11-16T18:04:32.059Z'
            description: The identifier for a particular seat
            key: seat-number
            name: Seat number
            schema:
              $ref: >-
                https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number
            updated_at: '2022-11-16T18:04:32.059Z'
            version: 1
            visibility: VISIBILITY_READ_WRITE_VALUES
          - created_at: '2022-11-16T18:04:21.912Z'
            description: The identifier for a particular table
            key: table-number
            name: Table number
            schema:
              $ref: >-
                https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number
            updated_at: '2022-11-16T18:04:21.912Z'
            version: 1
            visibility: VISIBILITY_READ_WRITE_VALUES
    ListOrderCustomAttributesRequest:
      type: object
      description: Represents a list request for order custom attributes.
      x-release-status: BETA
      x-params-example: >-
        ?order_id=7BbXGEIWNldxAzrtGf9GPVZTwZ4F&with_definitions=true&visibility_filter=ALL&limit=4
      properties:
        visibility_filter:
          $ref: '#/components/schemas/VisibilityFilter'
          description: >-
            Requests that all of the custom attributes be returned, or only
            those that are read-only or read-write.

            See [VisibilityFilter](#type-visibilityfilter) for possible values
          nullable: true
        cursor:
          type: string
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint. 

            Provide this cursor to retrieve the next page of results for your
            original request. 

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          minLength: 1
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory. 

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100. 

            The default value is 20.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          minimum: 1
          maximum: 100
          nullable: true
        with_definitions:
          type: boolean
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of each

            custom attribute. Set this parameter to `true` to get the name and
            description of each custom attribute, 

            information about the data type, or other definition details. The
            default value is `false`.
          nullable: true
    ListOrderCustomAttributesResponse:
      type: object
      description: Represents a response from listing order custom attributes.
      x-release-status: BETA
      properties:
        custom_attributes:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The retrieved custom attributes. If no custom attribute are found,
            Square returns an empty object (`{}`).
        cursor:
          type: string
          description: >-
            The cursor to provide in your next call to this endpoint to retrieve
            the next page of results for your original request. 

            This field is present only if the request succeeded and additional
            results are available.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          minLength: 1
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attributes:
          - created_at: '2022-11-10T17:31:36.111Z'
            key: wayne-test-15
            updated_at: '2022-11-10T17:31:36.111Z'
            value: TEST
            version: 1
            visibility: VISIBILITY_READ_WRITE_VALUES
    ListPaymentLinksRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            If a cursor is not provided, the endpoint returns the first page of
            the results.

            For more  information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        limit:
          type: integer
          description: >-
            A limit on the number of results to return per page. The limit is
            advisory and

            the implementation might return more or less results. If the
            supplied limit is negative, zero, or

            greater than the maximum limit of 1000, it is ignored.


            Default value: `100`
          nullable: true
    ListPaymentLinksResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
        payment_links:
          type: array
          items:
            $ref: '#/components/schemas/PaymentLink'
          description: The list of payment links.
        cursor:
          type: string
          description: >2-
              When a response is truncated, it includes a cursor that you can use in a subsequent request
            to retrieve the next set of gift cards. If a cursor is not present,
            this is the final response.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        cursor: MTY1NQ==
        payment_links:
          - checkout_options:
              ask_for_shipping_address: true
            created_at: '2022-04-26T00:15:15Z'
            id: TN4BWEDJ9AI5MBIV
            order_id: Qqc6yppGvxVwc46Cch4zHTaJqc4F
            payment_note: test
            updated_at: '2022-04-26T00:18:24Z'
            url: https://square.link/u/EXAMPLE
            version: 2
          - created_at: '2022-04-11T23:14:59Z'
            description: ''
            id: RY5UNCUMPJN5XKCT
            order_id: EmBmGt3zJD15QeO1dxzBTxMxtwfZY
            url: https://square.link/u/EXAMPLE
            version: 1
    ListPaymentRefundsRequest:
      type: object
      description: |-
        Describes a request to list refunds using
        [ListPaymentRefunds](api-endpoint:Refunds-ListPaymentRefunds).

        The maximum results per page is 100.
      x-release-status: PUBLIC
      properties:
        begin_time:
          type: string
          description: >-
            Indicates the start of the time range to retrieve each
            `PaymentRefund` for, in RFC 3339 

            format.  The range is determined using the `created_at` field for
            each `PaymentRefund`. 


            Default: The current time minus one year.
          nullable: true
        end_time:
          type: string
          description: >-
            Indicates the end of the time range to retrieve each `PaymentRefund`
            for, in RFC 3339 

            format.  The range is determined using the `created_at` field for
            each `PaymentRefund`.


            Default: The current time.
          nullable: true
        sort_order:
          type: string
          description: |-
            The order in which results are listed by `PaymentRefund.created_at`:
            - `ASC` - Oldest to newest.
            - `DESC` - Newest to oldest (default).
          nullable: true
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        location_id:
          type: string
          description: >-
            Limit results to the location supplied. By default, results are
            returned

            for all locations associated with the seller.
          nullable: true
        status:
          type: string
          description: >-
            If provided, only refunds with the given status are returned.

            For a list of refund status values, see
            [PaymentRefund](entity:PaymentRefund).


            Default: If omitted, refunds are returned regardless of their
            status.
          nullable: true
        source_type:
          type: string
          description: >-
            If provided, only returns refunds whose payments have the indicated
            source type.

            Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, and
            `EXTERNAL`.

            For information about these payment source types, see

            [Take
            Payments](https://developer.squareup.com/docs/payments-api/take-payments).


            Default: If omitted, refunds are returned regardless of the source
            type.
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to be returned in a single page.


            It is possible to receive fewer results than the specified limit on
            a given page.


            If the supplied value is greater than 100, no more than 100 results
            are returned.


            Default: 100
          nullable: true
      example: {}
    ListPaymentRefundsResponse:
      type: object
      description: >-
        Defines the response returned by
        [ListPaymentRefunds](api-endpoint:Refunds-ListPaymentRefunds).


        Either `errors` or `refunds` is present in a given response (never
        both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/PaymentRefund'
          description: The list of requested refunds.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,

            this is the final response.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        cursor: >-
          5evquW1YswHoT4EoyUhzMmTsCnsSXBU9U0WJ4FU4623nrMQcocH0RGU6Up1YkwfiMcF59ood58EBTEGgzMTGHQJpocic7ExOL0NtrTXCeWcv0UJIJNk8eXb
        refunds:
          - amount_money:
              amount: 555
              currency: USD
            created_at: '2021-10-13T19:59:05.342Z'
            id: >-
              bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY_69MmgHubkLqx9wGhnmenRUHOaKitE6llfZuxcWYjGxd
            location_id: L88917AVBK2S5
            order_id: 9ltv0bx5PuvGXUYHYHxYSKEqC3IZY
            payment_id: bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY
            processing_fee:
              - amount_money:
                  amount: -34
                  currency: USD
                effective_at: '2021-10-13T21:34:35.000Z'
                type: INITIAL
            reason: Example Refund
            status: COMPLETED
            updated_at: '2021-10-13T20:00:03.497Z'
    ListPaymentsRequest:
      type: object
      description: |-
        Describes a request to list payments using 
        [ListPayments](api-endpoint:Payments-ListPayments). 

        The maximum results per page is 100.
      x-release-status: PUBLIC
      properties:
        begin_time:
          type: string
          description: >-
            Indicates the start of the time range to retrieve payments for, in
            RFC 3339 format.  

            The range is determined using the `created_at` field for each
            Payment.

            Inclusive. Default: The current time minus one year.
          nullable: true
        end_time:
          type: string
          description: >-
            Indicates the end of the time range to retrieve payments for, in RFC
            3339 format.  The 

            range is determined using the `created_at` field for each Payment.


            Default: The current time.
          nullable: true
        sort_order:
          type: string
          description: >-
            The order in which results are listed by
            `ListPaymentsRequest.sort_field`:

            - `ASC` - Oldest to newest.

            - `DESC` - Newest to oldest (default).
          nullable: true
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        location_id:
          type: string
          description: >-
            Limit results to the location supplied. By default, results are
            returned

            for the default (main) location associated with the seller.
          nullable: true
        total:
          type: integer
          description: The exact amount in the `total_money` for a payment.
          format: int64
          nullable: true
        last_4:
          type: string
          description: The last four digits of a payment card.
          nullable: true
        card_brand:
          type: string
          description: The brand of the payment card (for example, VISA).
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to be returned in a single page.

            It is possible to receive fewer results than the specified limit on
            a given page.


            The default value of 100 is also the maximum allowed value. If the
            provided value is 

            greater than 100, it is ignored and the default value is used
            instead.


            Default: `100`
          nullable: true
        is_offline_payment:
          type: boolean
          description: Whether the payment was taken offline or not.
          nullable: true
        offline_begin_time:
          type: string
          description: >-
            Indicates the start of the time range for which to retrieve offline
            payments, in RFC 3339

            format for timestamps. The range is determined using the

            `offline_payment_details.client_created_at` field for each Payment.
            If set, payments without a

            value set in `offline_payment_details.client_created_at` will not be
            returned.


            Default: The current time.
          nullable: true
        offline_end_time:
          type: string
          description: >-
            Indicates the end of the time range for which to retrieve offline
            payments, in RFC 3339

            format for timestamps. The range is determined using the

            `offline_payment_details.client_created_at` field for each Payment.
            If set, payments without a

            value set in `offline_payment_details.client_created_at` will not be
            returned.


            Default: The current time.
          nullable: true
        updated_at_begin_time:
          type: string
          description: >-
            Indicates the start of the time range to retrieve payments for, in
            RFC 3339 format.  The

            range is determined using the `updated_at` field for each Payment.
          nullable: true
        updated_at_end_time:
          type: string
          description: >-
            Indicates the end of the time range to retrieve payments for, in RFC
            3339 format.  The

            range is determined using the `updated_at` field for each Payment.
          nullable: true
        sort_field:
          $ref: '#/components/schemas/PaymentSortField'
          description: |-
            The field used to sort results by. The default is `CREATED_AT`.
            See [PaymentSortField](#type-paymentsortfield) for possible values
          nullable: true
      example: {}
    ListPaymentsResponse:
      type: object
      description: >-
        Defines the response returned by
        [ListPayments](api-endpoint:Payments-ListPayments).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
          description: The requested list of payments.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,

            this is the final response.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        payments:
          - amount_money:
              amount: 555
              currency: USD
            application_details:
              application_id: sq0ids-Pw67AZAlLVB7hsRmwlJPuA
              square_product: VIRTUAL_TERMINAL
            approved_money:
              amount: 555
              currency: USD
            card_details:
              auth_result_code: 2Nkw7q
              avs_status: AVS_ACCEPTED
              card:
                bin: '411111'
                card_brand: VISA
                card_type: DEBIT
                exp_month: 11
                exp_year: 2022
                fingerprint: >-
                  sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ
                last_4: '1111'
                prepaid_type: NOT_PREPAID
              card_payment_timeline:
                authorized_at: '2021-10-13T19:34:33.680Z'
                captured_at: '2021-10-13T19:34:34.340Z'
              cvv_status: CVV_ACCEPTED
              entry_method: KEYED
              statement_description: SQ *EXAMPLE TEST GOSQ.C
              status: CAPTURED
            created_at: '2021-10-13T19:34:33.524Z'
            delay_action: CANCEL
            delay_duration: PT168H
            delayed_until: '2021-10-20T19:34:33.524Z'
            employee_id: TMoK_ogh6rH1o4dV
            id: bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY
            location_id: L88917AVBK2S5
            note: Test Note
            order_id: d7eKah653Z579f3gVtjlxpSlmUcZY
            processing_fee:
              - amount_money:
                  amount: 34
                  currency: USD
                effective_at: '2021-10-13T21:34:35.000Z'
                type: INITIAL
            receipt_number: bP9m
            receipt_url: https://squareup.com/receipt/preview/bP9mAsEMYPUGjjGNaNO5ZDVyLhSZY
            source_type: CARD
            status: COMPLETED
            team_member_id: TMoK_ogh6rH1o4dV
            total_money:
              amount: 555
              currency: USD
            updated_at: '2021-10-13T19:34:37.261Z'
            version_token: vguW2km0KpVCdAXZcNTZ438qg5LlVPTP4HO5OpiHNfa6o
    ListPayoutEntriesRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            The order in which payout entries are listed.
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

            If request parameters change between requests, subsequent results
            may contain duplicates or missing records.
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to be returned in a single page.

            It is possible to receive fewer results than the specified limit on
            a given page.

            The default value of 100 is also the maximum allowed value. If the
            provided value is

            greater than 100, it is ignored and the default value is used
            instead.

            Default: `100`
          nullable: true
      example: {}
    ListPayoutEntriesResponse:
      type: object
      description: The response to retrieve payout records entries.
      x-release-status: PUBLIC
      properties:
        payout_entries:
          type: array
          items:
            $ref: '#/components/schemas/PayoutEntry'
          description: >-
            The requested list of payout entries, ordered with the given or
            default sort order.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example:
        cursor: TbfI80z98Xc2LdApCyZ2NvCYLpkPurYLR16GRIttpMJ55mrSIMzHgtkcRQdT0mOnTtfHO
        payout_entries:
          - effective_at: '2021-12-14T23:31:49Z'
            fee_amount_money:
              amount: -2
              currency_code: USD
            gross_amount_money:
              amount: -50
              currency_code: USD
            id: poe_ZQWcw41d0SGJS6IWd4cSi8mKHk
            net_amount_money:
              amount: -48
              currency_code: USD
            payout_id: po_4d28e6c4-7dd5-4de4-8ec9-a059277646a6
            type: REFUND
            type_refund_details:
              payment_id: HVdG62HeMlti8YYf94oxrN
              refund_id: HVdG62HeMlti8YYf94oxrN_dR8Nztxg7umf94oxrN12Ji5r2KW14FAY
          - effective_at: '2021-12-14T23:31:49Z'
            fee_amount_money:
              amount: 19
              currency_code: USD
            gross_amount_money:
              amount: 100
              currency_code: USD
            id: poe_EibbY9Ob1d0SGJS6IWd4cSiSi6wkaPk
            net_amount_money:
              amount: 81
              currency_code: USD
            payout_id: po_4d28e6c4-7dd5-4de4-8ec9-a059277646a6
            type: CHARGE
            type_charge_details:
              payment_id: HVdG62H5K3291d0SGJS6IWd4cSi8YY
    ListPayoutsRequest:
      type: object
      description: A request to retrieve payout records.
      x-release-status: PUBLIC
      properties:
        location_id:
          type: string
          description: >-
            The ID of the location for which to list the payouts.

            By default, payouts are returned for the default (main) location
            associated with the seller.
          maxLength: 255
          nullable: true
        status:
          $ref: '#/components/schemas/PayoutStatus'
          description: If provided, only payouts with the given status are returned.
          nullable: true
        begin_time:
          type: string
          description: >-
            The timestamp for the beginning of the payout creation time, in RFC
            3339 format.

            Inclusive. Default: The current time minus one year.
          nullable: true
        end_time:
          type: string
          description: >-
            The timestamp for the end of the payout creation time, in RFC 3339
            format.

            Default: The current time.
          nullable: true
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            The order in which payouts are listed.
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

            If request parameters change between requests, subsequent results
            may contain duplicates or missing records.
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to be returned in a single page.

            It is possible to receive fewer results than the specified limit on
            a given page.

            The default value of 100 is also the maximum allowed value. If the
            provided value is

            greater than 100, it is ignored and the default value is used
            instead.

            Default: `100`
          nullable: true
      example: {}
    ListPayoutsResponse:
      type: object
      description: The response to retrieve payout records entries.
      x-release-status: PUBLIC
      properties:
        payouts:
          type: array
          items:
            $ref: '#/components/schemas/Payout'
          description: The requested list of payouts.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,
            this is the final response.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example:
        cursor: EMPCyStibo64hS8wLayZPp3oedR3AeEUNd3z7u6zphi72LQZFIEMbkKVvot9eefpU
        payouts:
          - amount_money:
              amount: 6259
              currency_code: USD
            arrival_date: '2022-03-29'
            created_at: '2022-03-29T16:12:31Z'
            destination:
              id: ccof:ZPp3oedR3AeEUNd3z7
              type: CARD
            end_to_end_id: L2100000005
            id: po_b345d2c7-90b3-4f0b-a2aa-df1def7f8afc
            location_id: L88917AVBK2S5
            payout_fee:
              - amount_money:
                  amount: 95
                  currency_code: USD
                effective_at: '2022-03-29T16:12:31Z'
                type: TRANSFER_FEE
            status: PAID
            type: BATCH
            updated_at: '2022-03-30T01:07:22.875Z'
            version: 2
          - amount_money:
              amount: -103
              currency_code: USD
            arrival_date: '2022-03-24'
            created_at: '2022-03-24T03:07:09Z'
            destination:
              id: bact:ZPp3oedR3AeEUNd3z7
              type: BANK_ACCOUNT
            end_to_end_id: L2100000006
            id: po_f3c0fb38-a5ce-427d-b858-52b925b72e45
            location_id: L88917AVBK2S5
            status: PAID
            type: BATCH
            updated_at: '2022-03-24T03:07:09Z'
            version: 1
    ListRefundsRequest:
      type: object
      description: >-
        Defines the query parameters that can be included in

        a request to the [ListRefunds](api-endpoint:Transactions-ListRefunds)
        endpoint.


        Deprecated - recommend using
        [SearchOrders](api-endpoint:Orders-SearchOrders)
      x-release-status: DEPRECATED
      x-params-example: '?begin_time=2016-01-15T00:00:00Z&end_time=2016-01-31T00:00:00Z'
      properties:
        begin_time:
          type: string
          description: >-
            The beginning of the requested reporting period, in RFC 3339 format.


            See [Date
            ranges](https://developer.squareup.com/docs/build-basics/working-with-dates)
            for details on date inclusivity/exclusivity.


            Default value: The current time minus one year.
          nullable: true
        end_time:
          type: string
          description: >-
            The end of the requested reporting period, in RFC 3339 format.


            See [Date
            ranges](https://developer.squareup.com/docs/build-basics/working-with-dates)
            for details on date inclusivity/exclusivity.


            Default value: The current time.
          nullable: true
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            The order in which results are listed in the response (`ASC` for
            oldest first, `DESC` for newest first).

            Default value: `DESC`
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for your original
            query.


            See [Paginating
            results](https://developer.squareup.com/docs/working-with-apis/pagination)
            for more information.
          nullable: true
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/ListRefunds/ListRefundsRequest.csharp
        java: /sdk_samples/ListRefunds/ListRefundsRequest.java
        javascript: /sdk_samples/ListRefunds/ListRefundsRequest.javascript
        php: /sdk_samples/ListRefunds/ListRefundsRequest.php
        python: /sdk_samples/ListRefunds/ListRefundsRequest.python
        ruby: /sdk_samples/ListRefunds/ListRefundsRequest.ruby
    ListRefundsResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [ListRefunds](api-endpoint:Transactions-ListRefunds)
        endpoint.


        One of `errors` or `refunds` is present in a given response (never
        both).
      x-release-status: DEPRECATED
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
          description: An array of refunds that match your query.
        cursor:
          type: string
          description: >-
            A pagination cursor for retrieving the next set of results,

            if any remain. Provide this value as the `cursor` parameter in a
            subsequent

            request to this endpoint.


            See [Paginating
            results](https://developer.squareup.com/docs/working-with-apis/pagination)
            for more information.
      example:
        refunds:
          - additional_recipients:
              - amount_money:
                  amount: 10
                  currency: USD
                description: Application fees
                location_id: 057P5VYJ4A5X1
            amount_money:
              amount: 100
              currency: USD
            created_at: '2016-01-20T00:28:18Z'
            id: b27436d1-7f8e-5610-45c6-417ef71434b4-SW
            location_id: 18YC4JDH91E1H
            reason: some reason
            status: APPROVED
            tender_id: MtZRYYdDrYNQbOvV7nbuBvMF
            transaction_id: KnL67ZIwXCPtzOrqj0HrkxMF
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/ListRefunds/ListRefundsResponse.csharp
        java: /sdk_samples/ListRefunds/ListRefundsResponse.java
        javascript: /sdk_samples/ListRefunds/ListRefundsResponse.javascript
        php: /sdk_samples/ListRefunds/ListRefundsResponse.php
        python: /sdk_samples/ListRefunds/ListRefundsResponse.python
        ruby: /sdk_samples/ListRefunds/ListRefundsResponse.ruby
    ListSitesRequest:
      type: object
      description: Represents a `ListSites` request.
      x-release-status: PUBLIC
      properties: {}
    ListSitesResponse:
      type: object
      description: >-
        Represents a `ListSites` response. The response can include either
        `sites` or `errors`.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        sites:
          type: array
          items:
            $ref: '#/components/schemas/Site'
          description: The sites that belong to the seller.
      example:
        sites:
          - created_at: '2020-10-28T13:22:51.000000Z'
            domain: mysite2.square.site
            id: site_278075276488921835
            is_published: false
            site_title: My Second Site
            updated_at: '2020-10-28T13:22:51.000000Z'
          - created_at: '2020-06-18T17:45:13.000000Z'
            domain: mysite1.square.site
            id: site_102725345836253849
            is_published: true
            site_title: My First Site
            updated_at: '2020-11-23T02:19:10.000000Z'
    ListSubscriptionEventsRequest:
      type: object
      description: >-
        Defines input parameters in a request to the 

        [ListSubscriptionEvents](api-endpoint:Subscriptions-ListSubscriptionEvents)

        endpoint.
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: >-
            When the total number of resulting subscription events exceeds the
            limit of a paged response, 

            specify the cursor returned from a preceding response here to fetch
            the next set of results.

            If the cursor is unset, the response contains the last page of the
            results.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          nullable: true
        limit:
          type: integer
          description: |-
            The upper limit on the number of subscription events to return
            in a paged response.
          minimum: 1
          nullable: true
    ListSubscriptionEventsResponse:
      type: object
      description: >-
        Defines output parameters in a response from the

        [ListSubscriptionEvents](api-endpoint:Subscriptions-ListSubscriptionEvents).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered during the request.
        subscription_events:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionEvent'
          description: The retrieved subscription events.
        cursor:
          type: string
          description: >-
            When the total number of resulting subscription events exceeds the
            limit of a paged response, 

            the response includes a cursor for you to use in a subsequent
            request to fetch the next set of events.

            If the cursor is unset, the response contains the last page of the
            results.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        subscription_events:
          - effective_date: '2020-04-24'
            id: 06809161-3867-4598-8269-8aea5be4f9de
            plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
            subscription_event_type: START_SUBSCRIPTION
          - effective_date: '2020-05-01'
            id: f2736603-cd2e-47ec-8675-f815fff54f88
            info:
              code: CUSTOMER_NO_NAME
              detail: >-
                The customer with ID `V74BMG0GPS2KNCWJE1BTYJ37Y0` does not have
                a name on record.
            plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
            subscription_event_type: DEACTIVATE_SUBSCRIPTION
          - effective_date: '2022-05-01'
            id: b426fc85-6859-450b-b0d0-fe3a5d1b565f
            plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
            subscription_event_type: RESUME_SUBSCRIPTION
          - effective_date: '2022-09-01'
            id: 09f14de1-2f53-4dae-9091-49aa53f83d01
            plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
            subscription_event_type: PAUSE_SUBSCRIPTION
          - effective_date: '2022-12-01'
            id: f28a73ac-1a1b-4b0f-8eeb-709a72945776
            plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
            subscription_event_type: RESUME_SUBSCRIPTION
          - effective_date: '2023-04-01'
            id: 1eee8790-472d-4efe-8c69-8ad84e9cefe0
            plan_variation_id: 02CD53CFA4d1498AFAD42
            subscription_event_type: PLAN_CHANGE
          - effective_date: '2023-06-21'
            id: a0c08083-5db0-4800-85c7-d398de4fbb6e
            plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
            subscription_event_type: STOP_SUBSCRIPTION
    ListTeamMemberBookingProfilesRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        bookable_only:
          type: boolean
          description: >-
            Indicates whether to include only bookable team members in the
            returned result (`true`) or not (`false`).
          nullable: true
        limit:
          type: integer
          description: The maximum number of results to return in a paged response.
          minimum: 1
          maximum: 100
          nullable: true
        cursor:
          type: string
          description: >-
            The pagination cursor from the preceding response to return the next
            page of the results. Do not set this when retrieving the first page
            of the results.
          maxLength: 65536
          nullable: true
        location_id:
          type: string
          description: >-
            Indicates whether to include only team members enabled at the given
            location in the returned result.
          maxLength: 32
          nullable: true
    ListTeamMemberBookingProfilesResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        team_member_booking_profiles:
          type: array
          items:
            $ref: '#/components/schemas/TeamMemberBookingProfile'
          description: >-
            The list of team member booking profiles. The results are returned
            in the ascending order of the time

            when the team member booking profiles were last updated. Multiple
            booking profiles updated at the same time

            are further sorted in the ascending order of their IDs.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in the subsequent request to get
            the next page of the results. Stop retrieving the next page of the
            results when the cursor is not set.
          maxLength: 65536
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
      example:
        errors: []
        team_member_booking_profiles:
          - display_name: Sandbox Seller
            is_bookable: true
            team_member_id: TMXUrsBWWcHTt79t
          - display_name: Sandbox Staff
            is_bookable: true
            team_member_id: TMaJcbiRqPIGZuS9
    ListTeamMemberWagesRequest:
      type: object
      description: A request for a set of `TeamMemberWage` objects.
      x-release-status: PUBLIC
      x-params-example: >-
        ?team_member_id=33fJchumvVdJwxV0H6L9&limit=4&cursor=s4R0Z6ecFTzTC4jz8sUDBQTudX3KE313OT9fCt3VUgsXM4sMgED
      properties:
        team_member_id:
          type: string
          description: |-
            Filter the returned wages to only those that are associated with the
            specified team member.
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of `TeamMemberWage` results to return per page.
            The number can range between

            1 and 200. The default is 200.
          minimum: 1
          maximum: 200
          nullable: true
        cursor:
          type: string
          description: A pointer to the next page of `EmployeeWage` results to fetch.
          nullable: true
    ListTeamMemberWagesResponse:
      type: object
      description: >-
        The response to a request for a set of `TeamMemberWage` objects. The
        response contains

        a set of `TeamMemberWage` objects.
      x-release-status: PUBLIC
      properties:
        team_member_wages:
          type: array
          items:
            $ref: '#/components/schemas/TeamMemberWage'
          description: A page of `TeamMemberWage` results.
        cursor:
          type: string
          description: |-
            The value supplied in the subsequent request to fetch the next page
            of `TeamMemberWage` results.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        cursor: 2fofTniCgT0yIPAq26kmk0YyFQJZfbWkh73OOnlTHmTAx13NgED
        team_member_wages:
          - hourly_rate:
              amount: 3250
              currency: USD
            id: pXS3qCv7BERPnEGedM4S8mhm
            job_id: jxJNN6eCJsLrhg5UFJrDWDGE
            team_member_id: 33fJchumvVdJwxV0H6L9
            tip_eligible: false
            title: Manager
          - hourly_rate:
              amount: 2600
              currency: USD
            id: rZduCkzYDUVL3ovh1sQgbue6
            job_id: gcbz15vKGnMKmaWJJ152kjim
            team_member_id: 33fJchumvVdJwxV0H6L9
            tip_eligible: true
            title: Cook
          - hourly_rate:
              amount: 1600
              currency: USD
            id: FxLbs5KpPUHa8wyt5ctjubDX
            job_id: FzbJAtt9qEWncK1BWgVCxQ6M
            team_member_id: 33fJchumvVdJwxV0H6L9
            tip_eligible: true
            title: Barista
          - hourly_rate:
              amount: 1700
              currency: USD
            id: vD1wCgijMDR3cX5TPnu7VXto
            job_id: N4YKVLzFj3oGtNocqoYHYpW3
            team_member_id: 33fJchumvVdJwxV0H6L9
            tip_eligible: true
            title: Cashier
    ListTransactionsRequest:
      type: object
      description: >-
        Defines the query parameters that can be included in

        a request to the
        [ListTransactions](api-endpoint:Transactions-ListTransactions) endpoint.


        Deprecated - recommend using
        [SearchOrders](api-endpoint:Orders-SearchOrders)
      x-release-status: DEPRECATED
      x-params-example: '?begin_time=2016-01-15T00:00:00Z&end_time=2016-01-31T00:00:00Z'
      properties:
        begin_time:
          type: string
          description: >-
            The beginning of the requested reporting period, in RFC 3339 format.


            See [Date
            ranges](https://developer.squareup.com/docs/build-basics/working-with-dates)
            for details on date inclusivity/exclusivity.


            Default value: The current time minus one year.
          nullable: true
        end_time:
          type: string
          description: >-
            The end of the requested reporting period, in RFC 3339 format.


            See [Date
            ranges](https://developer.squareup.com/docs/build-basics/working-with-dates)
            for details on date inclusivity/exclusivity.


            Default value: The current time.
          nullable: true
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            The order in which results are listed in the response (`ASC` for
            oldest first, `DESC` for newest first).

            Default value: `DESC`
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for your original
            query.


            See [Paginating
            results](https://developer.squareup.com/docs/working-with-apis/pagination)
            for more information.
          nullable: true
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/ListTransactions/ListTransactionsRequest.csharp
        java: /sdk_samples/ListTransactions/ListTransactionsRequest.java
        javascript: /sdk_samples/ListTransactions/ListTransactionsRequest.javascript
        php: /sdk_samples/ListTransactions/ListTransactionsRequest.php
        python: /sdk_samples/ListTransactions/ListTransactionsRequest.python
        ruby: /sdk_samples/ListTransactions/ListTransactionsRequest.ruby
    ListTransactionsResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [ListTransactions](api-endpoint:Transactions-ListTransactions) endpoint.


        One of `errors` or `transactions` is present in a given response (never
        both).
      x-release-status: DEPRECATED
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        transactions:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
          description: An array of transactions that match your query.
        cursor:
          type: string
          description: >-
            A pagination cursor for retrieving the next set of results,

            if any remain. Provide this value as the `cursor` parameter in a
            subsequent

            request to this endpoint.


            See [Paginating
            results](https://developer.squareup.com/docs/working-with-apis/pagination)
            for more information.
      example:
        transactions:
          - created_at: '2016-01-20T22:57:56Z'
            id: KnL67ZIwXCPtzOrqj0HrkxMF
            location_id: 18YC4JDH91E1H
            product: EXTERNAL_API
            reference_id: some optional reference id
            refunds:
              - additional_recipients:
                  - amount_money:
                      amount: 100
                      currency: USD
                    description: Application fees
                    location_id: 057P5VYJ4A5X1
                amount_money:
                  amount: 5000
                  currency: USD
                created_at: '2016-01-20T22:59:20Z'
                id: 7a5RcVI0CxbOcJ2wMOkE
                location_id: 18YC4JDH91E1H
                processing_fee_money:
                  amount: 138
                  currency: USD
                reason: some reason why
                status: APPROVED
                tender_id: MtZRYYdDrYNQbOvV7nbuBvMF
                transaction_id: KnL67ZIwXCPtzOrqj0HrkxMF
            tenders:
              - additional_recipients:
                  - amount_money:
                      amount: 20
                      currency: USD
                    description: Application fees
                    location_id: 057P5VYJ4A5X1
                amount_money:
                  amount: 5000
                  currency: USD
                card_details:
                  card:
                    card_brand: VISA
                    last_4: '1111'
                  entry_method: KEYED
                  status: CAPTURED
                created_at: '2016-01-20T22:57:56Z'
                id: MtZRYYdDrYNQbOvV7nbuBvMF
                location_id: 18YC4JDH91E1H
                note: some optional note
                processing_fee_money:
                  amount: 138
                  currency: USD
                transaction_id: KnL67ZIwXCPtzOrqj0HrkxMF
                type: CARD
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/ListTransactions/ListTransactionsResponse.csharp
        java: /sdk_samples/ListTransactions/ListTransactionsResponse.java
        javascript: /sdk_samples/ListTransactions/ListTransactionsResponse.javascript
        php: /sdk_samples/ListTransactions/ListTransactionsResponse.php
        python: /sdk_samples/ListTransactions/ListTransactionsResponse.python
        ruby: /sdk_samples/ListTransactions/ListTransactionsResponse.ruby
    ListWebhookEventTypesRequest:
      type: object
      description: Lists all webhook event types that can be subscribed to.
      x-release-status: PUBLIC
      properties:
        api_version:
          type: string
          description: >-
            The API version for which to list event types. Setting this field
            overrides the default version used by the application.
          nullable: true
    ListWebhookEventTypesResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [ListWebhookEventTypes](api-endpoint:WebhookSubscriptions-ListWebhookEventTypes)
        endpoint.


        Note: if there are errors processing the request, the event types field
        will not be

        present.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        event_types:
          type: array
          items:
            type: string
          description: The list of event types.
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/EventTypeMetadata'
          description: >-
            Contains the metadata of a webhook event type. For more information,
            see [EventTypeMetadata](entity:EventTypeMetadata).
      example:
        event_types:
          - inventory.count.updated
        metadata:
          - api_version_introduced: '2018-07-12'
            event_type: inventory.count.updated
            release_status: PUBLIC
    ListWebhookSubscriptionsRequest:
      type: object
      description: >-
        Lists all [Subscription](entity:WebhookSubscription)s owned by your
        application.
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for your original
            query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          maxLength: 256
          nullable: true
        include_disabled:
          type: boolean
          description: >-
            Includes disabled [Subscription](entity:WebhookSubscription)s.

            By default, all enabled [Subscription](entity:WebhookSubscription)s
            are returned.
          nullable: true
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: >-
            Sorts the returned list by when the
            [Subscription](entity:WebhookSubscription) was created with the
            specified order.

            This field defaults to ASC.

            See [SortOrder](#type-sortorder) for possible values
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of results to be returned in a single page.

            It is possible to receive fewer results than the specified limit on
            a given page.

            The default value of 100 is also the maximum allowed value.


            Default: 100
          minimum: 1
          maximum: 100
          nullable: true
    ListWebhookSubscriptionsResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [ListWebhookSubscriptions](api-endpoint:WebhookSubscriptions-ListWebhookSubscriptions)
        endpoint.


        Note: if there are errors processing the request, the subscriptions
        field will not be

        present.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/WebhookSubscription'
          description: The requested list of [Subscription](entity:WebhookSubscription)s.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,

            this is the final response.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        subscriptions:
          - api_version: '2021-12-15'
            created_at: 2022-01-10 23:29:48 +0000 UTC
            enabled: true
            event_types:
              - payment.created
              - payment.updated
            id: wbhk_b35f6b3145074cf9ad513610786c19d5
            name: Example Webhook Subscription
            notification_url: https://example-webhook-url.com
            updated_at: 2022-01-10 23:29:48 +0000 UTC
    ListWorkweekConfigsRequest:
      type: object
      description: A request for a set of `WorkweekConfig` objects.
      x-release-status: PUBLIC
      x-params-example: '?limit=1&cursor=s4R0Z6ecFTzTC4jz8sUDBQTudX3KE313OT9fCt3VUgsXM4sMgED'
      properties:
        limit:
          type: integer
          description: The maximum number of `WorkweekConfigs` results to return per page.
          nullable: true
        cursor:
          type: string
          description: A pointer to the next page of `WorkweekConfig` results to fetch.
          nullable: true
    ListWorkweekConfigsResponse:
      type: object
      description: >-
        The response to a request for a set of `WorkweekConfig` objects. The
        response contains

        the requested `WorkweekConfig` objects and might contain a set of
        `Error` objects if

        the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        workweek_configs:
          type: array
          items:
            $ref: '#/components/schemas/WorkweekConfig'
          description: A page of `WorkweekConfig` results.
        cursor:
          type: string
          description: >-
            The value supplied in the subsequent request to fetch the next page
            of

            `WorkweekConfig` results.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        cursor: 2fofTniCgT0yIPAq26kmk0YyFQJZfbWkh73OOnlTHmTAx13NgED
        workweek_configs:
          - created_at: '2016-02-04T00:58:24Z'
            id: FY4VCAQN700GM
            start_of_day_local_time: '10:00'
            start_of_week: MON
            updated_at: '2019-02-28T01:04:35Z'
            version: 11
    Location:
      type: object
      description: >-
        Represents one of a business'
        [locations](https://developer.squareup.com/docs/locations-api).
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: >-
            A short generated string of letters and numbers that uniquely
            identifies this location instance.
          maxLength: 32
          readOnly: true
        name:
          type: string
          description: |-
            The name of the location.
            This information appears in the Seller Dashboard as the nickname.
            A location name must be unique within a seller account.
          maxLength: 255
          nullable: true
        address:
          $ref: '#/components/schemas/Address'
          description: The physical address of the location.
          nullable: true
        timezone:
          type: string
          description: |-
            The [IANA time zone](https://www.iana.org/time-zones) identifier for
            the time zone of the location. For example, `America/Los_Angeles`.
          maxLength: 30
          nullable: true
        capabilities:
          type: array
          items:
            $ref: '#/components/schemas/LocationCapability'
          description: >-
            The Square features that are enabled for the location.

            See [LocationCapability](entity:LocationCapability) for possible
            values.

            See [LocationCapability](#type-locationcapability) for possible
            values
          readOnly: true
        status:
          $ref: '#/components/schemas/LocationStatus'
          description: |-
            The status of the location.
            See [LocationStatus](#type-locationstatus) for possible values
          nullable: true
        created_at:
          type: string
          description: >-
            The time when the location was created, in RFC 3339 format.

            For more information, see [Working with
            Dates](https://developer.squareup.com/docs/build-basics/working-with-dates).
          minLength: 20
          maxLength: 25
          readOnly: true
        merchant_id:
          type: string
          description: The ID of the merchant that owns the location.
          maxLength: 32
          readOnly: true
        country:
          $ref: '#/components/schemas/Country'
          description: >-
            The country of the location, in the two-letter format of ISO 3166.
            For example, `US` or `JP`.


            See [Country](entity:Country) for possible values.

            See [Country](#type-country) for possible values
          readOnly: true
        language_code:
          type: string
          description: >-
            The language associated with the location, in

            [BCP 47 format](https://tools.ietf.org/html/bcp47#appendix-A).

            For more information, see [Language
            Preferences](https://developer.squareup.com/docs/build-basics/general-considerations/language-preferences).
          minLength: 2
          maxLength: 5
          nullable: true
        currency:
          $ref: '#/components/schemas/Currency'
          description: >-
            The currency used for all transactions at this location,

            in ISO 4217 format. For example, the currency code for US dollars is
            `USD`.

            See [Currency](entity:Currency) for possible values.

            See [Currency](#type-currency) for possible values
          readOnly: true
        phone_number:
          type: string
          description: The phone number of the location. For example, `+1 855-700-6000`.
          maxLength: 17
          nullable: true
        business_name:
          type: string
          description: >-
            The name of the location's overall business. This name is present on
            receipts and other customer-facing branding, and can be changed no
            more than three times in a twelve-month period.
          maxLength: 255
          nullable: true
        type:
          $ref: '#/components/schemas/LocationType'
          description: |-
            The type of the location.
            See [LocationType](#type-locationtype) for possible values
          nullable: true
        website_url:
          type: string
          description: >-
            The website URL of the location.  For example,
            `https://squareup.com`.
          maxLength: 255
          nullable: true
        business_hours:
          $ref: '#/components/schemas/BusinessHours'
          description: The hours of operation for the location.
          nullable: true
        business_email:
          type: string
          description: >-
            The email address of the location. This can be unique to the
            location and is not always the email address for the business owner
            or administrator.
          maxLength: 255
          nullable: true
        description:
          type: string
          description: >-
            The description of the location. For example, `Main Street
            location`.
          maxLength: 1024
          nullable: true
        twitter_username:
          type: string
          description: >-
            The Twitter username of the location without the '@' symbol. For
            example, `Square`.
          minLength: 1
          maxLength: 15
          nullable: true
        instagram_username:
          type: string
          description: >-
            The Instagram username of the location without the '@' symbol. For
            example, `square`.
          minLength: 1
          maxLength: 30
          nullable: true
        facebook_url:
          type: string
          description: >-
            The Facebook profile URL of the location. The URL should begin with
            'facebook.com/'. For example, `https://www.facebook.com/square`.
          maxLength: 255
          nullable: true
        coordinates:
          $ref: '#/components/schemas/Coordinates'
          description: The physical coordinates (latitude and longitude) of the location.
          nullable: true
        logo_url:
          type: string
          description: >-
            The URL of the logo image for the location. When configured in the
            Seller

            Dashboard (Receipts section), the logo appears on transactions (such
            as receipts and invoices) that Square generates on behalf of the
            seller.

            This image should have a roughly square (1:1) aspect ratio and
            should be at least 200x200 pixels.
          maxLength: 255
          readOnly: true
        pos_background_url:
          type: string
          description: The URL of the Point of Sale background image for the location.
          maxLength: 255
          readOnly: true
        mcc:
          type: string
          description: >-
            A four-digit number that describes the kind of goods or services
            sold at the location.

            The [merchant category code
            (MCC)](https://developer.squareup.com/docs/locations-api#initialize-a-merchant-category-code)
            of the location as standardized by ISO 18245.

            For example, `5045`, for a location that sells computer goods and
            software.
          minLength: 4
          maxLength: 4
          x-release-status: BETA
          nullable: true
        full_format_logo_url:
          type: string
          description: >-
            The URL of a full-format logo image for the location. When
            configured in the Seller

            Dashboard (Receipts section), the logo appears on transactions (such
            as receipts and invoices) that Square generates on behalf of the
            seller.

            This image can be wider than it is tall and should be at least
            1280x648 pixels.
          readOnly: true
        tax_ids:
          $ref: '#/components/schemas/TaxIds'
          description: The tax IDs for this location.
          readOnly: true
          x-release-status: BETA
    LocationBookingProfile:
      type: object
      description: >-
        The booking profile of a seller's location, including the location's ID
        and whether the location is enabled for online booking.
      x-release-status: PUBLIC
      properties:
        location_id:
          type: string
          description: The ID of the [location](entity:Location).
          nullable: true
        booking_site_url:
          type: string
          description: Url for the online booking site for this location.
          nullable: true
        online_booking_enabled:
          type: boolean
          description: Indicates whether the location is enabled for online booking.
          nullable: true
    LocationCapability:
      type: string
      enum:
        - CREDIT_CARD_PROCESSING
        - AUTOMATIC_TRANSFERS
        - UNLINKED_REFUNDS
      x-enum-elements:
        - name: CREDIT_CARD_PROCESSING
          description: The capability to process credit card transactions with Square.
        - name: AUTOMATIC_TRANSFERS
          description: The capability to receive automatic transfers from Square.
        - name: UNLINKED_REFUNDS
          description: The capability to process unlinked refunds with Square.
      description: The capabilities a location might have.
      x-release-status: PUBLIC
    LocationStatus:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
      x-enum-elements:
        - name: ACTIVE
          description: A location that is active for business.
        - name: INACTIVE
          description: >-
            A location that is not active for business. Inactive locations
            provide historical

            information. Hide inactive locations unless the user has requested
            to see them.
      description: A location's status.
      x-release-status: PUBLIC
    LocationType:
      type: string
      enum:
        - PHYSICAL
        - MOBILE
      x-enum-elements:
        - name: PHYSICAL
          description: A place of business with a physical location.
        - name: MOBILE
          description: >-
            A place of business that is mobile, such as a food truck or online
            store.
      description: A location's type.
      x-release-status: PUBLIC
    LoyaltyAccount:
      type: object
      description: >-
        Describes a loyalty account in a [loyalty
        program](entity:LoyaltyProgram). For more information, see

        [Create and Retrieve Loyalty
        Accounts](https://developer.squareup.com/docs/loyalty-api/loyalty-accounts).
      x-release-status: PUBLIC
      required:
        - program_id
      properties:
        id:
          type: string
          description: The Square-assigned ID of the loyalty account.
          maxLength: 36
          readOnly: true
        program_id:
          type: string
          description: >-
            The Square-assigned ID of the [loyalty
            program](entity:LoyaltyProgram) to which the account belongs.
          minLength: 1
          maxLength: 36
        balance:
          type: integer
          description: >-
            The available point balance in the loyalty account. If points are
            scheduled to expire, they are listed in the
            `expiring_point_deadlines` field.


            Your application should be able to handle loyalty accounts that have
            a negative point balance (`balance` is less than 0). This might
            occur if a seller makes a manual adjustment or as a result of a
            refund or exchange.
          readOnly: true
        lifetime_points:
          type: integer
          description: The total points accrued during the lifetime of the account.
          readOnly: true
        customer_id:
          type: string
          description: >-
            The Square-assigned ID of the [customer](entity:Customer) that is
            associated with the account.
          nullable: true
        enrolled_at:
          type: string
          description: >-
            The timestamp when the buyer joined the loyalty program, in RFC 3339
            format. This field is used to display the **Enrolled On** or
            **Member Since** date in first-party Square products.


            If this field is not set in a `CreateLoyaltyAccount` request, Square
            populates it after the buyer's first action on their account 

            (when `AccumulateLoyaltyPoints` or `CreateLoyaltyReward` is called).
            In first-party flows, Square populates the field when the buyer
            agrees to the terms of service in Square Point of Sale. 


            This field is typically specified in a `CreateLoyaltyAccount`
            request when creating a loyalty account for a buyer who already
            interacted with their account. 

            For example, you would set this field when migrating accounts from
            an external system. The timestamp in the request can represent a
            current or previous date and time, but it cannot be set for the
            future.
          nullable: true
        created_at:
          type: string
          description: >-
            The timestamp when the loyalty account was created, in RFC 3339
            format.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp when the loyalty account was last updated, in RFC 3339
            format.
          readOnly: true
        mapping:
          $ref: '#/components/schemas/LoyaltyAccountMapping'
          description: >-
            The mapping that associates the loyalty account with a buyer.
            Currently,

            a loyalty account can only be mapped to a buyer by phone number.


            To create a loyalty account, you must specify the `mapping` field,
            with the buyer's phone number

            in the `phone_number` field.
          nullable: true
        expiring_point_deadlines:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyAccountExpiringPointDeadline'
          description: >-
            The schedule for when points expire in the loyalty account balance.
            This field is present only if the account has points that are
            scheduled to expire. 


            The total number of points in this field equals the number of points
            in the `balance` field.
          nullable: true
    LoyaltyAccountExpiringPointDeadline:
      type: object
      description: >-
        Represents a set of points for a loyalty account that are scheduled to
        expire on a specific date.
      x-release-status: PUBLIC
      required:
        - points
        - expires_at
      properties:
        points:
          type: integer
          description: >-
            The number of points scheduled to expire at the `expires_at`
            timestamp.
        expires_at:
          type: string
          description: >-
            The timestamp of when the points are scheduled to expire, in RFC
            3339 format.
          minLength: 1
    LoyaltyAccountMapping:
      type: object
      description: >-
        Represents the mapping that associates a loyalty account with a buyer. 


        Currently, a loyalty account can only be mapped to a buyer by phone
        number. For more information, see 

        [Loyalty
        Overview](https://developer.squareup.com/docs/loyalty/overview).
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: The Square-assigned ID of the mapping.
          maxLength: 36
          readOnly: true
        created_at:
          type: string
          description: The timestamp when the mapping was created, in RFC 3339 format.
          readOnly: true
        phone_number:
          type: string
          description: >-
            The phone number of the buyer, in E.164 format. For example,
            "+14155551111".
          nullable: true
    LoyaltyAccountMappingType:
      type: string
      enum:
        - PHONE
      x-enum-elements:
        - name: PHONE
          description: The loyalty account is mapped by phone.
      description: The type of mapping.
      x-release-status: PUBLIC
    LoyaltyEvent:
      type: object
      description: >-
        Provides information about a loyalty event. 

        For more information, see [Search for Balance-Changing Loyalty
        Events](https://developer.squareup.com/docs/loyalty-api/loyalty-events).
      x-release-status: PUBLIC
      required:
        - id
        - type
        - created_at
        - loyalty_account_id
        - source
      properties:
        id:
          type: string
          description: The Square-assigned ID of the loyalty event.
          minLength: 1
          readOnly: true
        type:
          $ref: '#/components/schemas/LoyaltyEventType'
          description: |-
            The type of the loyalty event.
            See [LoyaltyEventType](#type-loyaltyeventtype) for possible values
          readOnly: true
        created_at:
          type: string
          description: The timestamp when the event was created, in RFC 3339 format.
          minLength: 1
          readOnly: true
        accumulate_points:
          $ref: '#/components/schemas/LoyaltyEventAccumulatePoints'
          description: Provides metadata when the event `type` is `ACCUMULATE_POINTS`.
          readOnly: true
        create_reward:
          $ref: '#/components/schemas/LoyaltyEventCreateReward'
          description: Provides metadata when the event `type` is `CREATE_REWARD`.
          readOnly: true
        redeem_reward:
          $ref: '#/components/schemas/LoyaltyEventRedeemReward'
          description: Provides metadata when the event `type` is `REDEEM_REWARD`.
          readOnly: true
        delete_reward:
          $ref: '#/components/schemas/LoyaltyEventDeleteReward'
          description: Provides metadata when the event `type` is `DELETE_REWARD`.
          readOnly: true
        adjust_points:
          $ref: '#/components/schemas/LoyaltyEventAdjustPoints'
          description: Provides metadata when the event `type` is `ADJUST_POINTS`.
          readOnly: true
        loyalty_account_id:
          type: string
          description: >-
            The ID of the [loyalty account](entity:LoyaltyAccount) associated
            with the event.
          minLength: 1
          maxLength: 36
          readOnly: true
        location_id:
          type: string
          description: The ID of the [location](entity:Location) where the event occurred.
          readOnly: true
        source:
          $ref: '#/components/schemas/LoyaltyEventSource'
          description: >-
            Defines whether the event was generated by the Square Point of Sale.

            See [LoyaltyEventSource](#type-loyaltyeventsource) for possible
            values
          readOnly: true
        expire_points:
          $ref: '#/components/schemas/LoyaltyEventExpirePoints'
          description: Provides metadata when the event `type` is `EXPIRE_POINTS`.
          readOnly: true
        other_event:
          $ref: '#/components/schemas/LoyaltyEventOther'
          description: Provides metadata when the event `type` is `OTHER`.
          readOnly: true
        accumulate_promotion_points:
          $ref: '#/components/schemas/LoyaltyEventAccumulatePromotionPoints'
          description: >-
            Provides metadata when the event `type` is
            `ACCUMULATE_PROMOTION_POINTS`.
          readOnly: true
    LoyaltyEventAccumulatePoints:
      type: object
      description: Provides metadata when the event `type` is `ACCUMULATE_POINTS`.
      x-release-status: PUBLIC
      properties:
        loyalty_program_id:
          type: string
          description: The ID of the [loyalty program](entity:LoyaltyProgram).
          maxLength: 36
          readOnly: true
        points:
          type: integer
          description: The number of points accumulated by the event.
          minimum: 1
          nullable: true
        order_id:
          type: string
          description: >-
            The ID of the [order](entity:Order) for which the buyer accumulated
            the points.

            This field is returned only if the Orders API is used to process
            orders.
          nullable: true
    LoyaltyEventAccumulatePromotionPoints:
      type: object
      description: >-
        Provides metadata when the event `type` is
        `ACCUMULATE_PROMOTION_POINTS`.
      x-release-status: PUBLIC
      required:
        - points
        - order_id
      properties:
        loyalty_program_id:
          type: string
          description: >-
            The Square-assigned ID of the [loyalty
            program](entity:LoyaltyProgram).
          maxLength: 36
          readOnly: true
        loyalty_promotion_id:
          type: string
          description: >-
            The Square-assigned ID of the [loyalty
            promotion](entity:LoyaltyPromotion).
          minLength: 1
          maxLength: 255
          readOnly: true
        points:
          type: integer
          description: The number of points earned by the event.
          readOnly: true
        order_id:
          type: string
          description: >-
            The ID of the [order](entity:Order) for which the buyer earned the
            promotion points.

            Only applications that use the Orders API to process orders can
            trigger this event.
          minLength: 1
          readOnly: true
    LoyaltyEventAdjustPoints:
      type: object
      description: Provides metadata when the event `type` is `ADJUST_POINTS`.
      x-release-status: PUBLIC
      required:
        - points
      properties:
        loyalty_program_id:
          type: string
          description: >-
            The Square-assigned ID of the [loyalty
            program](entity:LoyaltyProgram).
          maxLength: 36
          readOnly: true
        points:
          type: integer
          description: The number of points added or removed.
        reason:
          type: string
          description: The reason for the adjustment of points.
          nullable: true
    LoyaltyEventCreateReward:
      type: object
      description: Provides metadata when the event `type` is `CREATE_REWARD`.
      x-release-status: PUBLIC
      required:
        - loyalty_program_id
        - points
      properties:
        loyalty_program_id:
          type: string
          description: The ID of the [loyalty program](entity:LoyaltyProgram).
          minLength: 1
          maxLength: 36
          readOnly: true
        reward_id:
          type: string
          description: >-
            The Square-assigned ID of the created [loyalty
            reward](entity:LoyaltyReward).

            This field is returned only if the event source is `LOYALTY_API`.
          maxLength: 36
          readOnly: true
        points:
          type: integer
          description: The loyalty points used to create the reward.
          readOnly: true
    LoyaltyEventDateTimeFilter:
      type: object
      description: Filter events by date time range.
      x-release-status: PUBLIC
      required:
        - created_at
      properties:
        created_at:
          $ref: '#/components/schemas/TimeRange'
          description: The `created_at` date time range used to filter the result.
    LoyaltyEventDeleteReward:
      type: object
      description: Provides metadata when the event `type` is `DELETE_REWARD`.
      x-release-status: PUBLIC
      required:
        - loyalty_program_id
        - points
      properties:
        loyalty_program_id:
          type: string
          description: The ID of the [loyalty program](entity:LoyaltyProgram).
          minLength: 1
          maxLength: 36
          readOnly: true
        reward_id:
          type: string
          description: |-
            The ID of the deleted [loyalty reward](entity:LoyaltyReward).
            This field is returned only if the event source is `LOYALTY_API`.
          maxLength: 36
          readOnly: true
        points:
          type: integer
          description: The number of points returned to the loyalty account.
          readOnly: true
    LoyaltyEventExpirePoints:
      type: object
      description: Provides metadata when the event `type` is `EXPIRE_POINTS`.
      x-release-status: PUBLIC
      required:
        - loyalty_program_id
        - points
      properties:
        loyalty_program_id:
          type: string
          description: >-
            The Square-assigned ID of the [loyalty
            program](entity:LoyaltyProgram).
          minLength: 1
          maxLength: 36
          readOnly: true
        points:
          type: integer
          description: The number of points expired.
    LoyaltyEventFilter:
      type: object
      description: |-
        The filtering criteria. If the request specifies multiple filters, 
        the endpoint uses a logical AND to evaluate them.
      x-release-status: PUBLIC
      properties:
        loyalty_account_filter:
          $ref: '#/components/schemas/LoyaltyEventLoyaltyAccountFilter'
          description: Filter events by loyalty account.
          nullable: true
        type_filter:
          $ref: '#/components/schemas/LoyaltyEventTypeFilter'
          description: Filter events by event type.
          nullable: true
        date_time_filter:
          $ref: '#/components/schemas/LoyaltyEventDateTimeFilter'
          description: |-
            Filter events by date time range. 
            For each range, the start time is inclusive and the end time 
            is exclusive.
          nullable: true
        location_filter:
          $ref: '#/components/schemas/LoyaltyEventLocationFilter'
          description: Filter events by location.
          nullable: true
        order_filter:
          $ref: '#/components/schemas/LoyaltyEventOrderFilter'
          description: Filter events by the order associated with the event.
          nullable: true
    LoyaltyEventLocationFilter:
      type: object
      description: Filter events by location.
      x-release-status: PUBLIC
      required:
        - location_ids
      properties:
        location_ids:
          type: array
          items:
            type: string
          description: |-
            The [location](entity:Location) IDs for loyalty events to query.
            If multiple values are specified, the endpoint uses 
            a logical OR to combine them.
    LoyaltyEventLoyaltyAccountFilter:
      type: object
      description: Filter events by loyalty account.
      x-release-status: PUBLIC
      required:
        - loyalty_account_id
      properties:
        loyalty_account_id:
          type: string
          description: >-
            The ID of the [loyalty account](entity:LoyaltyAccount) associated
            with loyalty events.
          minLength: 1
    LoyaltyEventOrderFilter:
      type: object
      description: Filter events by the order associated with the event.
      x-release-status: PUBLIC
      required:
        - order_id
      properties:
        order_id:
          type: string
          description: The ID of the [order](entity:Order) associated with the event.
          minLength: 1
    LoyaltyEventOther:
      type: object
      description: Provides metadata when the event `type` is `OTHER`.
      x-release-status: PUBLIC
      required:
        - loyalty_program_id
        - points
      properties:
        loyalty_program_id:
          type: string
          description: >-
            The Square-assigned ID of the [loyalty
            program](entity:LoyaltyProgram).
          minLength: 1
          maxLength: 36
          readOnly: true
        points:
          type: integer
          description: The number of points added or removed.
    LoyaltyEventQuery:
      type: object
      description: Represents a query used to search for loyalty events.
      x-release-status: PUBLIC
      properties:
        filter:
          $ref: '#/components/schemas/LoyaltyEventFilter'
          description: The query filter criteria.
          nullable: true
    LoyaltyEventRedeemReward:
      type: object
      description: Provides metadata when the event `type` is `REDEEM_REWARD`.
      x-release-status: PUBLIC
      required:
        - loyalty_program_id
      properties:
        loyalty_program_id:
          type: string
          description: The ID of the [loyalty program](entity:LoyaltyProgram).
          minLength: 1
          maxLength: 36
          readOnly: true
        reward_id:
          type: string
          description: |-
            The ID of the redeemed [loyalty reward](entity:LoyaltyReward).
            This field is returned only if the event source is `LOYALTY_API`.
          maxLength: 36
          readOnly: true
        order_id:
          type: string
          description: >-
            The ID of the [order](entity:Order) that redeemed the reward.

            This field is returned only if the Orders API is used to process
            orders.
          readOnly: true
    LoyaltyEventSource:
      type: string
      enum:
        - SQUARE
        - LOYALTY_API
      x-enum-elements:
        - name: SQUARE
          description: The event is generated by the Square Point of Sale (POS).
        - name: LOYALTY_API
          description: >-
            The event is generated by something other than the Square Point of
            Sale that used the Loyalty API.
      description: Defines whether the event was generated by the Square Point of Sale.
      x-release-status: PUBLIC
    LoyaltyEventType:
      type: string
      enum:
        - ACCUMULATE_POINTS
        - CREATE_REWARD
        - REDEEM_REWARD
        - DELETE_REWARD
        - ADJUST_POINTS
        - EXPIRE_POINTS
        - OTHER
        - ACCUMULATE_PROMOTION_POINTS
      x-enum-elements:
        - name: ACCUMULATE_POINTS
          description: >-
            Points are added to a loyalty account for a purchase that

            qualified for points based on an [accrual
            rule](entity:LoyaltyProgramAccrualRule).
        - name: CREATE_REWARD
          description: A [loyalty reward](entity:LoyaltyReward) is created.
        - name: REDEEM_REWARD
          description: A loyalty reward is redeemed.
        - name: DELETE_REWARD
          description: A loyalty reward is deleted.
        - name: ADJUST_POINTS
          description: Loyalty points are manually adjusted.
        - name: EXPIRE_POINTS
          description: |-
            Loyalty points are expired according to the 
            expiration policy of the loyalty program.
        - name: OTHER
          description: Some other loyalty event occurred.
        - name: ACCUMULATE_PROMOTION_POINTS
          description: |2-
             Points are added to a loyalty account for a purchase that
            qualified for a [loyalty promotion](entity:LoyaltyPromotion).
      description: The type of the loyalty event.
      x-release-status: PUBLIC
    LoyaltyEventTypeFilter:
      type: object
      description: Filter events by event type.
      x-release-status: PUBLIC
      required:
        - types
      properties:
        types:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyEventType'
          description: |-
            The loyalty event types used to filter the result.
            If multiple values are specified, the endpoint uses a 
            logical OR to combine them.
            See [LoyaltyEventType](#type-loyaltyeventtype) for possible values
    LoyaltyProgram:
      type: object
      description: >-
        Represents a Square loyalty program. Loyalty programs define how buyers
        can earn points and redeem points for rewards. 

        Square sellers can have only one loyalty program, which is created and
        managed from the Seller Dashboard. 

        For more information, see [Loyalty Program
        Overview](https://developer.squareup.com/docs/loyalty/overview).
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: |-
            The Square-assigned ID of the loyalty program. Updates to 
            the loyalty program do not modify the identifier.
          maxLength: 36
          readOnly: true
        status:
          $ref: '#/components/schemas/LoyaltyProgramStatus'
          description: >-
            Whether the program is currently active.

            See [LoyaltyProgramStatus](#type-loyaltyprogramstatus) for possible
            values
          nullable: true
        reward_tiers:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyProgramRewardTier'
          description: The list of rewards for buyers, sorted by ascending points.
          nullable: true
        expiration_policy:
          $ref: '#/components/schemas/LoyaltyProgramExpirationPolicy'
          description: If present, details for how points expire.
          nullable: true
        terminology:
          $ref: '#/components/schemas/LoyaltyProgramTerminology'
          description: A cosmetic name for the points currency.
          nullable: true
        location_ids:
          type: array
          items:
            type: string
          description: The [locations](entity:Location) at which the program is active.
          nullable: true
        created_at:
          type: string
          description: The timestamp when the program was created, in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: The timestamp when the reward was last updated, in RFC 3339 format.
          readOnly: true
        accrual_rules:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyProgramAccrualRule'
          description: >-
            Defines how buyers can earn loyalty points from the base loyalty
            program.

            To check for associated [loyalty
            promotions](entity:LoyaltyPromotion) that enable

            buyers to earn extra points, call
            [ListLoyaltyPromotions](api-endpoint:Loyalty-ListLoyaltyPromotions).
          nullable: true
    LoyaltyProgramAccrualRule:
      type: object
      description: >-
        Represents an accrual rule, which defines how buyers can earn points
        from the base [loyalty program](entity:LoyaltyProgram).
      x-release-status: PUBLIC
      required:
        - accrual_type
      properties:
        accrual_type:
          $ref: '#/components/schemas/LoyaltyProgramAccrualRuleType'
          description: >-
            The type of the accrual rule that defines how buyers can earn
            points.

            See
            [LoyaltyProgramAccrualRuleType](#type-loyaltyprogramaccrualruletype)
            for possible values
        points:
          type: integer
          description: |-
            The number of points that 
            buyers earn based on the `accrual_type`.
          minimum: 1
          nullable: true
        visit_data:
          $ref: '#/components/schemas/LoyaltyProgramAccrualRuleVisitData'
          description: Additional data for rules with the `VISIT` accrual type.
          nullable: true
        spend_data:
          $ref: '#/components/schemas/LoyaltyProgramAccrualRuleSpendData'
          description: Additional data for rules with the `SPEND` accrual type.
          nullable: true
        item_variation_data:
          $ref: '#/components/schemas/LoyaltyProgramAccrualRuleItemVariationData'
          description: Additional data for rules with the `ITEM_VARIATION` accrual type.
          nullable: true
        category_data:
          $ref: '#/components/schemas/LoyaltyProgramAccrualRuleCategoryData'
          description: Additional data for rules with the `CATEGORY` accrual type.
          nullable: true
    LoyaltyProgramAccrualRuleCategoryData:
      type: object
      description: Represents additional data for rules with the `CATEGORY` accrual type.
      x-release-status: PUBLIC
      required:
        - category_id
      properties:
        category_id:
          type: string
          description: >-
            The ID of the `CATEGORY` [catalog object](entity:CatalogObject) that
            buyers can purchase to earn

            points.
          minLength: 1
    LoyaltyProgramAccrualRuleItemVariationData:
      type: object
      description: >-
        Represents additional data for rules with the `ITEM_VARIATION` accrual
        type.
      x-release-status: PUBLIC
      required:
        - item_variation_id
      properties:
        item_variation_id:
          type: string
          description: >-
            The ID of the `ITEM_VARIATION` [catalog
            object](entity:CatalogObject) that buyers can purchase to earn

            points.
          minLength: 1
    LoyaltyProgramAccrualRuleSpendData:
      type: object
      description: Represents additional data for rules with the `SPEND` accrual type.
      x-release-status: PUBLIC
      required:
        - amount_money
        - tax_mode
      properties:
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount that buyers must spend to earn points. 

            For example, given an "Earn 1 point for every $10 spent" accrual
            rule, a buyer who spends $105 earns 10 points.
        excluded_category_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of any `CATEGORY` catalog objects that are excluded from
            points accrual.


            You can use the
            [BatchRetrieveCatalogObjects](api-endpoint:Catalog-BatchRetrieveCatalogObjects)

            endpoint to retrieve information about the excluded categories.
          nullable: true
        excluded_item_variation_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of any `ITEM_VARIATION` catalog objects that are excluded
            from points accrual.


            You can use the
            [BatchRetrieveCatalogObjects](api-endpoint:Catalog-BatchRetrieveCatalogObjects)

            endpoint to retrieve information about the excluded item variations.
          nullable: true
        tax_mode:
          $ref: '#/components/schemas/LoyaltyProgramAccrualRuleTaxMode'
          description: >-
            Indicates how taxes should be treated when calculating the purchase
            amount used for points accrual.

            See
            [LoyaltyProgramAccrualRuleTaxMode](#type-loyaltyprogramaccrualruletaxmode)
            for possible values
    LoyaltyProgramAccrualRuleTaxMode:
      type: string
      enum:
        - BEFORE_TAX
        - AFTER_TAX
      x-enum-elements:
        - name: BEFORE_TAX
          description: >-
            Exclude taxes from the purchase amount used for loyalty points
            accrual.
        - name: AFTER_TAX
          description: >-
            Include taxes in the purchase amount used for loyalty points
            accrual.
      description: >-
        Indicates how taxes should be treated when calculating the purchase
        amount used for loyalty points accrual. 

        This setting applies only to `SPEND` accrual rules or `VISIT` accrual
        rules that have a minimum spend requirement.
      x-release-status: PUBLIC
    LoyaltyProgramAccrualRuleType:
      type: string
      enum:
        - VISIT
        - SPEND
        - ITEM_VARIATION
        - CATEGORY
      x-enum-elements:
        - name: VISIT
          description: |-
            A visit-based accrual rule. A buyer earns points for each visit. 
            You can specify the minimum purchase required.
        - name: SPEND
          description: >-
            A spend-based accrual rule. A buyer earns points based on the
            amount 

            spent.
        - name: ITEM_VARIATION
          description: |-
            An accrual rule based on an item variation. For example, accrue 
            points for purchasing a coffee.
        - name: CATEGORY
          description: >-
            An accrual rule based on an item category. For example, accrue
            points 

            for purchasing any item in the "hot drink" category: coffee, tea, or
            hot cocoa.
      description: The type of the accrual rule that defines how buyers can earn points.
      x-release-status: PUBLIC
    LoyaltyProgramAccrualRuleVisitData:
      type: object
      description: Represents additional data for rules with the `VISIT` accrual type.
      x-release-status: PUBLIC
      required:
        - tax_mode
      properties:
        minimum_amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The minimum purchase required during the visit to quality for
            points.
          nullable: true
        tax_mode:
          $ref: '#/components/schemas/LoyaltyProgramAccrualRuleTaxMode'
          description: >-
            Indicates how taxes should be treated when calculating the purchase
            amount to determine whether the visit qualifies for points. 

            This setting applies only if `minimum_amount_money` is specified.

            See
            [LoyaltyProgramAccrualRuleTaxMode](#type-loyaltyprogramaccrualruletaxmode)
            for possible values
    LoyaltyProgramExpirationPolicy:
      type: object
      description: Describes when the loyalty program expires.
      x-release-status: PUBLIC
      required:
        - expiration_duration
      properties:
        expiration_duration:
          type: string
          description: >-
            The number of months before points expire, in `P[n]M` RFC 3339
            duration format. For example, a value of `P12M` represents a
            duration of 12 months. 

            Points are valid through the last day of the month in which they are
            scheduled to expire. For example, with a  `P12M` duration, points
            earned on July 6, 2020 expire on August 1, 2021.
          minLength: 1
    LoyaltyProgramRewardDefinition:
      type: object
      description: >-
        Provides details about the reward tier discount. DEPRECATED at version
        2020-12-16. Discount details

        are now defined using a catalog pricing rule and other catalog objects.
        For more information, see

        [Getting discount details for a reward
        tier](https://developer.squareup.com/docs/loyalty-api/loyalty-rewards#get-discount-details).
      x-release-status: DEPRECATED
      required:
        - scope
        - discount_type
      properties:
        scope:
          $ref: '#/components/schemas/LoyaltyProgramRewardDefinitionScope'
          description: >-
            Indicates the scope of the reward tier. DEPRECATED at version
            2020-12-16. You can find this information in the

            `product_set_data` field of the `PRODUCT_SET` catalog object
            referenced by the pricing rule. For `ORDER` scopes,

            `all_products` is true. For `ITEM_VARIATION` or `CATEGORY` scopes,
            `product_ids_any` is a list of

            catalog object IDs of the given type.

            See
            [LoyaltyProgramRewardDefinitionScope](#type-loyaltyprogramrewarddefinitionscope)
            for possible values
          readOnly: true
        discount_type:
          $ref: '#/components/schemas/LoyaltyProgramRewardDefinitionType'
          description: >-
            The type of discount the reward tier offers. DEPRECATED at version
            2020-12-16. You can find this information

            in the `discount_data.discount_type` field of the `DISCOUNT` catalog
            object referenced by the pricing rule.

            See
            [LoyaltyProgramRewardDefinitionType](#type-loyaltyprogramrewarddefinitiontype)
            for possible values
          readOnly: true
        percentage_discount:
          type: string
          description: >-
            The fixed percentage of the discount. Present if `discount_type` is
            `FIXED_PERCENTAGE`.

            For example, a 7.25% off discount will be represented as "7.25".
            DEPRECATED at version 2020-12-16. You can find this

            information in the `discount_data.percentage` field of the
            `DISCOUNT` catalog object referenced by the pricing rule.
          readOnly: true
        catalog_object_ids:
          type: array
          items:
            type: string
          description: >-
            The list of catalog objects to which this reward can be applied.
            They are either all item-variation ids or category ids, depending on
            the `type` field.

            DEPRECATED at version 2020-12-16. You can find this information in
            the `product_set_data.product_ids_any` field

            of the `PRODUCT_SET` catalog object referenced by the pricing rule.
          readOnly: true
        fixed_discount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of the discount. Present if `discount_type` is
            `FIXED_AMOUNT`. For example, $5 off.

            DEPRECATED at version 2020-12-16. You can find this information in
            the `discount_data.amount_money` field of the 

            `DISCOUNT` catalog object referenced by the pricing rule.
          readOnly: true
        max_discount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            When `discount_type` is `FIXED_PERCENTAGE`, the maximum discount
            amount that can be applied.

            DEPRECATED at version 2020-12-16. You can find this information in
            the `discount_data.maximum_amount_money` field

            of the `DISCOUNT` catalog object referenced by the the pricing rule.
          readOnly: true
    LoyaltyProgramRewardDefinitionScope:
      type: string
      enum:
        - ORDER
        - ITEM_VARIATION
        - CATEGORY
      x-enum-elements:
        - name: ORDER
          description: The discount applies to the entire order.
        - name: ITEM_VARIATION
          description: The discount applies only to specific item variations.
        - name: CATEGORY
          description: The discount applies only to items in the given categories.
      description: >-
        Indicates the scope of the reward tier. DEPRECATED at version
        2020-12-16. Discount details

        are now defined using a catalog pricing rule and other catalog objects.
        For more information, see

        [Getting discount details for a reward
        tier](https://developer.squareup.com/docs/loyalty-api/loyalty-rewards#get-discount-details).
      x-release-status: DEPRECATED
    LoyaltyProgramRewardDefinitionType:
      type: string
      enum:
        - FIXED_AMOUNT
        - FIXED_PERCENTAGE
      x-enum-elements:
        - name: FIXED_AMOUNT
          description: The fixed amount discounted.
        - name: FIXED_PERCENTAGE
          description: The fixed percentage discounted.
      description: >-
        The type of discount the reward tier offers. DEPRECATED at version
        2020-12-16. Discount details

        are now defined using a catalog pricing rule and other catalog objects.
        For more information, see

        [Getting discount details for a reward
        tier](https://developer.squareup.com/docs/loyalty-api/loyalty-rewards#get-discount-details).
      x-release-status: DEPRECATED
    LoyaltyProgramRewardTier:
      type: object
      description: >-
        Represents a reward tier in a loyalty program. A reward tier defines how
        buyers can redeem points for a reward, such as the number of points
        required and the value and scope of the discount. A loyalty program can
        offer multiple reward tiers.
      x-release-status: PUBLIC
      required:
        - points
        - pricing_rule_reference
      properties:
        id:
          type: string
          description: The Square-assigned ID of the reward tier.
          maxLength: 36
          readOnly: true
        points:
          type: integer
          description: The points exchanged for the reward tier.
          minimum: 1
        name:
          type: string
          description: The name of the reward tier.
          readOnly: true
        definition:
          $ref: '#/components/schemas/LoyaltyProgramRewardDefinition'
          description: >-
            Provides details about the reward tier definition.

            DEPRECATED at version 2020-12-16. Replaced by the
            `pricing_rule_reference` field.
          readOnly: true
          x-release-status: DEPRECATED
        created_at:
          type: string
          description: The timestamp when the reward tier was created, in RFC 3339 format.
          readOnly: true
        pricing_rule_reference:
          $ref: '#/components/schemas/CatalogObjectReference'
          description: >-
            A reference to the specific version of a `PRICING_RULE` catalog
            object that contains information about the reward tier discount.


            Use `object_id` and `catalog_version` with the
            [RetrieveCatalogObject](api-endpoint:Catalog-RetrieveCatalogObject)
            endpoint

            to get discount details. Make sure to set `include_related_objects`
            to true in the request to retrieve all catalog objects

            that define the discount. For more information, see [Getting
            discount details for a reward
            tier](https://developer.squareup.com/docs/loyalty-api/loyalty-rewards#get-discount-details).
    LoyaltyProgramStatus:
      type: string
      enum:
        - INACTIVE
        - ACTIVE
      x-enum-elements:
        - name: INACTIVE
          description: |-
            The loyalty program does not have an active subscription. 
            Loyalty API requests fail.
        - name: ACTIVE
          description: >-
            The program is fully functional. The program has an active
            subscription.
      description: Indicates whether the program is currently active.
      x-release-status: PUBLIC
    LoyaltyProgramTerminology:
      type: object
      description: Represents the naming used for loyalty points.
      x-release-status: PUBLIC
      required:
        - one
        - other
      properties:
        one:
          type: string
          description: A singular unit for a point (for example, 1 point is called 1 star).
          minLength: 1
        other:
          type: string
          description: A plural unit for point (for example, 10 points is called 10 stars).
          minLength: 1
    LoyaltyPromotion:
      type: object
      description: >-
        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.
      x-release-status: PUBLIC
      required:
        - name
        - incentive
        - available_time
      properties:
        id:
          type: string
          description: The Square-assigned ID of the promotion.
          minLength: 1
          maxLength: 255
          readOnly: true
        name:
          type: string
          description: The name of the promotion.
          minLength: 1
          maxLength: 70
        incentive:
          $ref: '#/components/schemas/LoyaltyPromotionIncentive'
          description: >-
            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:
          $ref: '#/components/schemas/LoyaltyPromotionAvailableTimeData'
          description: >-
            The scheduling information that defines when purchases can qualify
            to earn points from an `ACTIVE` promotion.
        trigger_limit:
          $ref: '#/components/schemas/LoyaltyPromotionTriggerLimit'
          description: >-
            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.
          nullable: true
        status:
          $ref: '#/components/schemas/LoyaltyPromotionStatus'
          description: >-
            The current status of the promotion.

            See [LoyaltyPromotionStatus](#type-loyaltypromotionstatus) for
            possible values
          readOnly: true
        created_at:
          type: string
          description: The timestamp of when the promotion was created, in RFC 3339 format.
          readOnly: true
        canceled_at:
          type: string
          description: >-
            The timestamp of when the promotion was canceled, in RFC 3339
            format.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp when the promotion was last updated, in RFC 3339
            format.
          readOnly: true
        loyalty_program_id:
          type: string
          description: >-
            The ID of the [loyalty program](entity:LoyaltyProgram) associated
            with the promotion.
          readOnly: true
        minimum_spend_amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The minimum purchase amount required to earn promotion points. If
            specified, this amount is positive.
          nullable: true
        qualifying_item_variation_ids:
          type: array
          items:
            type: string
          description: >-
            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.
          nullable: true
        qualifying_category_ids:
          type: array
          items:
            type: string
          description: >-
            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.
          nullable: true
    LoyaltyPromotionAvailableTimeData:
      type: object
      description: >-
        Represents scheduling information that determines when purchases can
        qualify to earn points

        from a [loyalty promotion](entity:LoyaltyPromotion).
      x-release-status: PUBLIC
      required:
        - time_periods
      properties:
        start_date:
          type: string
          description: >-
            The date that the promotion starts, in `YYYY-MM-DD` format. Square
            populates this field

            based on the provided `time_periods`.
          readOnly: true
        end_date:
          type: string
          description: >-
            The date that the promotion ends, in `YYYY-MM-DD` format. Square
            populates this field

            based on the provided `time_periods`. If an end date is not
            specified, an `ACTIVE` promotion

            remains available until it is canceled.
          readOnly: true
        time_periods:
          type: array
          items:
            type: string
          description: >-
            A list of [iCalendar (RFC 5545)
            events](https://tools.ietf.org/html/rfc5545#section-3.6.1)

            (`VEVENT`). Each event represents an available time period per day
            or days of the week. 

            A day can have a maximum of one available time period.


            Only `DTSTART`, `DURATION`, and `RRULE` are supported. `DTSTART` and
            `DURATION` are required and

            timestamps must be in local (unzoned) time format. Include `RRULE`
            to specify recurring promotions,

            an end date (using the `UNTIL` keyword), or both. For more
            information, see

            [Available
            time](https://developer.squareup.com/docs/loyalty-api/loyalty-promotions#available-time).


            Note that `BEGIN:VEVENT` and `END:VEVENT` are optional in a
            `CreateLoyaltyPromotion` request

            but are always included in the response.
    LoyaltyPromotionIncentive:
      type: object
      description: >-
        Represents how points for a [loyalty promotion](entity:LoyaltyPromotion)
        are calculated,

        either by multiplying the points earned from the base program or by
        adding a specified number

        of points to the points earned from the base program.
      x-release-status: PUBLIC
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/LoyaltyPromotionIncentiveType'
          description: >-
            The type of points incentive.

            See
            [LoyaltyPromotionIncentiveType](#type-loyaltypromotionincentivetype)
            for possible values
        points_multiplier_data:
          $ref: '#/components/schemas/LoyaltyPromotionIncentivePointsMultiplierData'
          description: Additional data for a `POINTS_MULTIPLIER` incentive type.
          nullable: true
        points_addition_data:
          $ref: '#/components/schemas/LoyaltyPromotionIncentivePointsAdditionData'
          description: Additional data for a `POINTS_ADDITION` incentive type.
          nullable: true
    LoyaltyPromotionIncentivePointsAdditionData:
      type: object
      description: >-
        Represents the metadata for a `POINTS_ADDITION` type of [loyalty
        promotion incentive](entity:LoyaltyPromotionIncentive).
      x-release-status: PUBLIC
      required:
        - points_addition
      properties:
        points_addition:
          type: integer
          description: >-
            The number of additional points to earn each time the promotion is
            triggered. For example,

            suppose a purchase qualifies for 5 points from the base loyalty
            program. If the purchase also

            qualifies for a `POINTS_ADDITION` promotion incentive with a
            `points_addition` of 3, the buyer

            earns a total of 8 points (5 program points + 3 promotion points = 8
            points).
          minimum: 1
    LoyaltyPromotionIncentivePointsMultiplierData:
      type: object
      description: >-
        Represents the metadata for a `POINTS_MULTIPLIER` type of [loyalty
        promotion incentive](entity:LoyaltyPromotionIncentive).
      x-release-status: PUBLIC
      properties:
        points_multiplier:
          type: integer
          description: >-
            The multiplier used to calculate the number of points earned each
            time the promotion

            is triggered. For example, suppose a purchase qualifies for 5 points
            from the base loyalty program.

            If the purchase also qualifies for a `POINTS_MULTIPLIER` promotion
            incentive with a `points_multiplier`

            of 3, the buyer earns a total of 15 points (5 program points x 3
            promotion multiplier = 15 points).


            DEPRECATED at version 2023-08-16. Replaced by the `multiplier`
            field.


            One of the following is required when specifying a points
            multiplier:

            - (Recommended) The `multiplier` field.

            - This deprecated `points_multiplier` field. If provided in the
            request, Square also returns `multiplier`

            with the equivalent value.
          minimum: 2
          maximum: 10
          x-release-status: DEPRECATED
          nullable: true
        multiplier:
          type: string
          description: >-
            The multiplier used to calculate the number of points earned each
            time the promotion is triggered,

            specified as a string representation of a decimal. Square supports
            multipliers up to 10x, with three

            point precision for decimal multipliers. For example, suppose a
            purchase qualifies for 4 points from the

            base loyalty program. If the purchase also qualifies for a
            `POINTS_MULTIPLIER` promotion incentive with a

            `multiplier` of "1.5", the buyer earns a total of 6 points (4
            program points x 1.5 promotion multiplier = 6 points).

            Fractional points are dropped.


            One of the following is required when specifying a points
            multiplier:

            - (Recommended) This `multiplier` field.

            - The deprecated `points_multiplier` field. If provided in the
            request, Square also returns `multiplier`

            with the equivalent value.
          maxLength: 5
          nullable: true
    LoyaltyPromotionIncentiveType:
      type: string
      enum:
        - POINTS_MULTIPLIER
        - POINTS_ADDITION
      x-enum-elements:
        - name: POINTS_MULTIPLIER
          description: |-
            Multiply the number of points earned from the base loyalty program.
            For example, "Earn double points."
        - name: POINTS_ADDITION
          description: >-
            Add a specified number of points to those earned from the base
            loyalty program.

            For example, "Earn 10 additional points."
      description: >-
        Indicates the type of points incentive for a [loyalty
        promotion](entity:LoyaltyPromotion),

        which is used to determine how buyers can earn points from the
        promotion.
      x-release-status: PUBLIC
    LoyaltyPromotionStatus:
      type: string
      enum:
        - ACTIVE
        - ENDED
        - CANCELED
        - SCHEDULED
      x-enum-elements:
        - name: ACTIVE
          description: >-
            The loyalty promotion is currently active. Buyers can earn points
            for purchases

            that meet the promotion conditions, such as the promotion's
            `available_time`.
        - name: ENDED
          description: >-
            The loyalty promotion has ended because the specified `end_date` was
            reached.

            `ENDED` is a terminal status.
        - name: CANCELED
          description: The loyalty promotion was canceled. `CANCELED` is a terminal status.
        - name: SCHEDULED
          description: >-
            The loyalty promotion is scheduled to start in the future. Square
            changes the

            promotion status to `ACTIVE` when the `start_date` is reached.
      description: Indicates the status of a [loyalty promotion](entity:LoyaltyPromotion).
      x-release-status: PUBLIC
    LoyaltyPromotionTriggerLimit:
      type: object
      description: >-
        Represents the number of times a buyer can earn points during a [loyalty
        promotion](entity:LoyaltyPromotion).

        If this field is not set, buyers can trigger the promotion an unlimited
        number of times to earn points during

        the time that the promotion is available.


        A purchase that is disqualified from earning points because of this
        limit might qualify for another active promotion.
      x-release-status: PUBLIC
      required:
        - times
      properties:
        times:
          type: integer
          description: >-
            The maximum number of times a buyer can trigger the promotion during
            the specified `interval`.
          minimum: 1
          maximum: 30
        interval:
          $ref: '#/components/schemas/LoyaltyPromotionTriggerLimitInterval'
          description: >-
            The time period the limit applies to.

            See
            [LoyaltyPromotionTriggerLimitInterval](#type-loyaltypromotiontriggerlimitinterval)
            for possible values
          nullable: true
    LoyaltyPromotionTriggerLimitInterval:
      type: string
      enum:
        - ALL_TIME
        - DAY
      x-enum-elements:
        - name: ALL_TIME
          description: >-
            The limit applies to the entire time that the promotion is active.
            For example, if `times`

            is set to 1 and `time_period` is set to `ALL_TIME`, a buyer can earn
            promotion points a maximum

            of one time during the promotion.
        - name: DAY
          description: >-
            The limit applies per day, according to the `available_time`
            schedule specified for the promotion.

            For example, if the `times` field of the trigger limit is set to 1,
            a buyer can trigger the promotion

            a maximum of once per day.
      description: >-
        Indicates the time period that the [trigger
        limit](entity:LoyaltyPromotionTriggerLimit) applies to,

        which is used to determine the number of times a buyer can earn points
        for a [loyalty promotion](entity:LoyaltyPromotion).
      x-release-status: PUBLIC
    LoyaltyReward:
      type: object
      description: >-
        Represents a contract to redeem loyalty points for a [reward
        tier](entity:LoyaltyProgramRewardTier) discount. Loyalty rewards can be
        in an ISSUED, REDEEMED, or DELETED state. 

        For more information, see [Manage loyalty
        rewards](https://developer.squareup.com/docs/loyalty-api/loyalty-rewards).
      x-release-status: PUBLIC
      required:
        - loyalty_account_id
        - reward_tier_id
      properties:
        id:
          type: string
          description: The Square-assigned ID of the loyalty reward.
          maxLength: 36
          readOnly: true
        status:
          $ref: '#/components/schemas/LoyaltyRewardStatus'
          description: >-
            The status of a loyalty reward.

            See [LoyaltyRewardStatus](#type-loyaltyrewardstatus) for possible
            values
          readOnly: true
        loyalty_account_id:
          type: string
          description: >-
            The Square-assigned ID of the [loyalty
            account](entity:LoyaltyAccount) to which the reward belongs.
          minLength: 1
          maxLength: 36
        reward_tier_id:
          type: string
          description: >-
            The Square-assigned ID of the [reward
            tier](entity:LoyaltyProgramRewardTier) used to create the reward.
          minLength: 1
          maxLength: 36
        points:
          type: integer
          description: The number of loyalty points used for the reward.
          minimum: 1
          readOnly: true
        order_id:
          type: string
          description: >-
            The Square-assigned ID of the [order](entity:Order) to which the
            reward is attached.
          nullable: true
        created_at:
          type: string
          description: The timestamp when the reward was created, in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: The timestamp when the reward was last updated, in RFC 3339 format.
          readOnly: true
        redeemed_at:
          type: string
          description: The timestamp when the reward was redeemed, in RFC 3339 format.
          readOnly: true
    LoyaltyRewardStatus:
      type: string
      enum:
        - ISSUED
        - REDEEMED
        - DELETED
      x-enum-elements:
        - name: ISSUED
          description: The reward is issued.
        - name: REDEEMED
          description: The reward is redeemed.
        - name: DELETED
          description: The reward is deleted.
      description: The status of the loyalty reward.
      x-release-status: PUBLIC
    MeasurementUnit:
      type: object
      description: >-
        Represents a unit of measurement to use with a quantity, such as ounces

        or inches. Exactly one of the following fields are required:
        `custom_unit`,

        `area_unit`, `length_unit`, `volume_unit`, and `weight_unit`.
      x-release-status: PUBLIC
      properties:
        custom_unit:
          $ref: '#/components/schemas/MeasurementUnitCustom'
          description: >-
            A custom unit of measurement defined by the seller using the Point
            of Sale

            app or ad-hoc as an order line item.
          nullable: true
        area_unit:
          $ref: '#/components/schemas/MeasurementUnitArea'
          description: >-
            Represents a standard area unit.

            See [MeasurementUnitArea](#type-measurementunitarea) for possible
            values
          nullable: true
        length_unit:
          $ref: '#/components/schemas/MeasurementUnitLength'
          description: >-
            Represents a standard length unit.

            See [MeasurementUnitLength](#type-measurementunitlength) for
            possible values
          nullable: true
        volume_unit:
          $ref: '#/components/schemas/MeasurementUnitVolume'
          description: >-
            Represents a standard volume unit.

            See [MeasurementUnitVolume](#type-measurementunitvolume) for
            possible values
          nullable: true
        weight_unit:
          $ref: '#/components/schemas/MeasurementUnitWeight'
          description: >-
            Represents a standard unit of weight or mass.

            See [MeasurementUnitWeight](#type-measurementunitweight) for
            possible values
          nullable: true
        generic_unit:
          $ref: '#/components/schemas/MeasurementUnitGeneric'
          description: >-
            Reserved for API integrations that lack the ability to specify a
            real measurement unit

            See [MeasurementUnitGeneric](#type-measurementunitgeneric) for
            possible values
          nullable: true
        time_unit:
          $ref: '#/components/schemas/MeasurementUnitTime'
          description: >-
            Represents a standard unit of time.

            See [MeasurementUnitTime](#type-measurementunittime) for possible
            values
          nullable: true
        type:
          $ref: '#/components/schemas/MeasurementUnitUnitType'
          description: >-
            Represents the type of the measurement unit.

            See [MeasurementUnitUnitType](#type-measurementunitunittype) for
            possible values
          nullable: true
    MeasurementUnitArea:
      type: string
      enum:
        - IMPERIAL_ACRE
        - IMPERIAL_SQUARE_INCH
        - IMPERIAL_SQUARE_FOOT
        - IMPERIAL_SQUARE_YARD
        - IMPERIAL_SQUARE_MILE
        - METRIC_SQUARE_CENTIMETER
        - METRIC_SQUARE_METER
        - METRIC_SQUARE_KILOMETER
      x-enum-elements:
        - name: IMPERIAL_ACRE
          description: The area is measured in acres.
        - name: IMPERIAL_SQUARE_INCH
          description: The area is measured in square inches.
        - name: IMPERIAL_SQUARE_FOOT
          description: The area is measured in square feet.
        - name: IMPERIAL_SQUARE_YARD
          description: The area is measured in square yards.
        - name: IMPERIAL_SQUARE_MILE
          description: The area is measured in square miles.
        - name: METRIC_SQUARE_CENTIMETER
          description: The area is measured in square centimeters.
        - name: METRIC_SQUARE_METER
          description: The area is measured in square meters.
        - name: METRIC_SQUARE_KILOMETER
          description: The area is measured in square kilometers.
      description: Unit of area used to measure a quantity.
      x-release-status: PUBLIC
    MeasurementUnitCustom:
      type: object
      description: The information needed to define a custom unit, provided by the seller.
      x-release-status: PUBLIC
      required:
        - name
        - abbreviation
      properties:
        name:
          type: string
          description: The name of the custom unit, for example "bushel".
        abbreviation:
          type: string
          description: >-
            The abbreviation of the custom unit, such as "bsh" (bushel). This
            appears

            in the cart for the Point of Sale app, and in reports.
    MeasurementUnitGeneric:
      type: string
      enum:
        - UNIT
      x-enum-elements:
        - name: UNIT
          description: The generic unit.
      x-release-status: PUBLIC
    MeasurementUnitLength:
      type: string
      enum:
        - IMPERIAL_INCH
        - IMPERIAL_FOOT
        - IMPERIAL_YARD
        - IMPERIAL_MILE
        - METRIC_MILLIMETER
        - METRIC_CENTIMETER
        - METRIC_METER
        - METRIC_KILOMETER
      x-enum-elements:
        - name: IMPERIAL_INCH
          description: The length is measured in inches.
        - name: IMPERIAL_FOOT
          description: The length is measured in feet.
        - name: IMPERIAL_YARD
          description: The length is measured in yards.
        - name: IMPERIAL_MILE
          description: The length is measured in miles.
        - name: METRIC_MILLIMETER
          description: The length is measured in millimeters.
        - name: METRIC_CENTIMETER
          description: The length is measured in centimeters.
        - name: METRIC_METER
          description: The length is measured in meters.
        - name: METRIC_KILOMETER
          description: The length is measured in kilometers.
      description: The unit of length used to measure a quantity.
      x-release-status: PUBLIC
    MeasurementUnitTime:
      type: string
      enum:
        - GENERIC_MILLISECOND
        - GENERIC_SECOND
        - GENERIC_MINUTE
        - GENERIC_HOUR
        - GENERIC_DAY
      x-enum-elements:
        - name: GENERIC_MILLISECOND
          description: The time is measured in milliseconds.
        - name: GENERIC_SECOND
          description: The time is measured in seconds.
        - name: GENERIC_MINUTE
          description: The time is measured in minutes.
        - name: GENERIC_HOUR
          description: The time is measured in hours.
        - name: GENERIC_DAY
          description: The time is measured in days.
      description: Unit of time used to measure a quantity (a duration).
      x-release-status: PUBLIC
    MeasurementUnitUnitType:
      type: string
      enum:
        - TYPE_CUSTOM
        - TYPE_AREA
        - TYPE_LENGTH
        - TYPE_VOLUME
        - TYPE_WEIGHT
        - TYPE_GENERIC
      x-enum-elements:
        - name: TYPE_CUSTOM
          description: The unit details are contained in the custom_unit field.
        - name: TYPE_AREA
          description: The unit details are contained in the area_unit field.
        - name: TYPE_LENGTH
          description: The unit details are contained in the length_unit field.
        - name: TYPE_VOLUME
          description: The unit details are contained in the volume_unit field.
        - name: TYPE_WEIGHT
          description: The unit details are contained in the weight_unit field.
        - name: TYPE_GENERIC
          description: The unit details are contained in the generic_unit field.
      description: >-
        Describes the type of this unit and indicates which field contains the
        unit information. This is an open enum.
      x-release-status: PUBLIC
    MeasurementUnitVolume:
      type: string
      enum:
        - GENERIC_FLUID_OUNCE
        - GENERIC_SHOT
        - GENERIC_CUP
        - GENERIC_PINT
        - GENERIC_QUART
        - GENERIC_GALLON
        - IMPERIAL_CUBIC_INCH
        - IMPERIAL_CUBIC_FOOT
        - IMPERIAL_CUBIC_YARD
        - METRIC_MILLILITER
        - METRIC_LITER
      x-enum-elements:
        - name: GENERIC_FLUID_OUNCE
          description: The volume is measured in ounces.
        - name: GENERIC_SHOT
          description: The volume is measured in shots.
        - name: GENERIC_CUP
          description: The volume is measured in cups.
        - name: GENERIC_PINT
          description: The volume is measured in pints.
        - name: GENERIC_QUART
          description: The volume is measured in quarts.
        - name: GENERIC_GALLON
          description: The volume is measured in gallons.
        - name: IMPERIAL_CUBIC_INCH
          description: The volume is measured in cubic inches.
        - name: IMPERIAL_CUBIC_FOOT
          description: The volume is measured in cubic feet.
        - name: IMPERIAL_CUBIC_YARD
          description: The volume is measured in cubic yards.
        - name: METRIC_MILLILITER
          description: The volume is measured in metric milliliters.
        - name: METRIC_LITER
          description: The volume is measured in metric liters.
      description: The unit of volume used to measure a quantity.
      x-release-status: PUBLIC
    MeasurementUnitWeight:
      type: string
      enum:
        - IMPERIAL_WEIGHT_OUNCE
        - IMPERIAL_POUND
        - IMPERIAL_STONE
        - METRIC_MILLIGRAM
        - METRIC_GRAM
        - METRIC_KILOGRAM
      x-enum-elements:
        - name: IMPERIAL_WEIGHT_OUNCE
          description: The weight is measured in ounces.
        - name: IMPERIAL_POUND
          description: The weight is measured in pounds.
        - name: IMPERIAL_STONE
          description: The weight is measured in stones.
        - name: METRIC_MILLIGRAM
          description: The weight is measured in milligrams.
        - name: METRIC_GRAM
          description: The weight is measured in grams.
        - name: METRIC_KILOGRAM
          description: The weight is measured in kilograms.
      description: Unit of weight used to measure a quantity.
      x-release-status: PUBLIC
    Merchant:
      type: object
      description: Represents a business that sells with Square.
      x-release-status: PUBLIC
      required:
        - country
      properties:
        id:
          type: string
          description: The Square-issued ID of the merchant.
        business_name:
          type: string
          description: The name of the merchant's overall business.
          nullable: true
        country:
          $ref: '#/components/schemas/Country'
          description: >-
            The country code associated with the merchant, in the two-letter
            format of ISO 3166. For example, `US` or `JP`.

            See [Country](#type-country) for possible values
        language_code:
          type: string
          description: >-
            The code indicating the [language
            preferences](https://developer.squareup.com/docs/build-basics/general-considerations/language-preferences)
            of the merchant, in [BCP 47
            format](https://tools.ietf.org/html/bcp47#appendix-A). For example,
            `en-US` or `fr-CA`.
          nullable: true
        currency:
          $ref: '#/components/schemas/Currency'
          description: >-
            The currency associated with the merchant, in ISO 4217 format. For
            example, the currency code for US dollars is `USD`.

            See [Currency](#type-currency) for possible values
          nullable: true
        status:
          $ref: '#/components/schemas/MerchantStatus'
          description: |-
            The merchant's status.
            See [MerchantStatus](#type-merchantstatus) for possible values
          nullable: true
        main_location_id:
          type: string
          description: >-
            The ID of the [main
            `Location`](https://developer.squareup.com/docs/locations-api#about-the-main-location)
            for this merchant.
          nullable: true
        created_at:
          type: string
          description: |-
            The time when the merchant was created, in RFC 3339 format.
               For more information, see [Working with Dates](https://developer.squareup.com/docs/build-basics/working-with-dates).
          readOnly: true
    MerchantStatus:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
      x-enum-elements:
        - name: ACTIVE
          description: >-
            A fully operational merchant account. The merchant can interact with
            Square products and APIs.
        - name: INACTIVE
          description: >-
            A functionally limited merchant account. The merchant can only have
            limited interaction

            via Square APIs. The merchant cannot log in or access the seller
            dashboard.
      x-release-status: PUBLIC
    ModifierLocationOverrides:
      type: object
      description: >-
        Location-specific overrides for specified properties of a
        `CatalogModifier` object.
      x-release-status: PUBLIC
      properties:
        location_id:
          type: string
          description: >-
            The ID of the `Location` object representing the location. This can
            include a deactivated location.
          nullable: true
        price_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The overridden price at the specified location. If this is
            unspecified, the modifier price is not overridden.

            The modifier becomes free of charge at the specified location, when
            this `price_money` field is set to 0.
          nullable: true
        sold_out:
          type: boolean
          description: >-
            Indicates whether the modifier is sold out at the specified location
            or not. As an example, for cheese (modifier) burger (item), when the
            modifier is sold out, it is the cheese, but not the burger, that is
            sold out.

            The seller can manually set this sold out status. Attempts by an
            application to set this attribute are ignored.
          readOnly: true
    Money:
      type: object
      description: >-
        Represents an amount of money. `Money` fields can be signed or unsigned.

        Fields that do not explicitly define whether they are signed or unsigned
        are

        considered unsigned and can only hold positive amounts. For signed
        fields, the

        sign of the value indicates the purpose of the money transfer. See

        [Working with Monetary
        Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts)

        for more information.
      x-release-status: PUBLIC
      properties:
        amount:
          type: integer
          description: >-
            The amount of money, in the smallest denomination of the currency

            indicated by `currency`. For example, when `currency` is `USD`,
            `amount` is

            in cents. Monetary amounts can be positive or negative. See the
            specific

            field description to determine the meaning of the sign in a
            particular case.
          format: int64
          nullable: true
        currency:
          $ref: '#/components/schemas/Currency'
          description: >-
            The type of currency, in __ISO 4217 format__. For example, the
            currency

            code for US dollars is `USD`.


            See [Currency](entity:Currency) for possible values.

            See [Currency](#type-currency) for possible values
          nullable: true
    ObtainTokenRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - client_id
        - grant_type
      properties:
        client_id:
          type: string
          description: >-
            The Square-issued ID of your application, which is available on the
            **OAuth** page in the

            [Developer Dashboard](https://developer.squareup.com/apps).
          maxLength: 191
        client_secret:
          type: string
          description: >-
            The Square-issued application secret for your application, which is
            available on the **OAuth** page

            in the [Developer Dashboard](https://developer.squareup.com/apps).
            This parameter is only required when 

            you're not using the [OAuth PKCE (Proof Key for Code Exchange)
            flow](https://developer.squareup.com/docs/oauth-api/overview#pkce-flow).

            The PKCE flow requires a `code_verifier` instead of a
            `client_secret` when `grant_type` is set to `authorization_code`. 

            If `grant_type` is set to `refresh_token` and the `refresh_token` is
            obtained uaing PKCE, the PKCE flow only requires `client_id`, 

            `grant_type`, and `refresh_token`.
          minLength: 2
          maxLength: 1024
          nullable: true
        code:
          type: string
          description: >-
            The authorization code to exchange.

            This code is required if `grant_type` is set to `authorization_code`
            to indicate that

            the application wants to exchange an authorization code for an OAuth
            access token.
          maxLength: 191
          nullable: true
        redirect_uri:
          type: string
          description: >-
            The redirect URL assigned on the **OAuth** page for your application
            in the [Developer Dashboard](https://developer.squareup.com/apps).
          maxLength: 2048
          nullable: true
        grant_type:
          type: string
          description: >-
            Specifies the method to request an OAuth access token.

            Valid values are `authorization_code`, `refresh_token`, and
            `migration_token`.
          minLength: 10
          maxLength: 20
        refresh_token:
          type: string
          description: >-
            A valid refresh token for generating a new OAuth access token.


            A valid refresh token is required if `grant_type` is set to
            `refresh_token`

            to indicate that the application wants a replacement for an expired
            OAuth access token.
          minLength: 2
          maxLength: 1024
          nullable: true
        migration_token:
          type: string
          description: >-
            A legacy OAuth access token obtained using a Connect API version
            prior

            to 2019-03-13. This parameter is required if `grant_type` is set to

            `migration_token` to indicate that the application wants to get a
            replacement

            OAuth access token. The response also returns a refresh token.

            For more information, see [Migrate to Using Refresh
            Tokens](https://developer.squareup.com/docs/oauth-api/migrate-to-refresh-tokens).
          minLength: 2
          maxLength: 1024
          nullable: true
        scopes:
          type: array
          items:
            type: string
          description: >-
            A JSON list of strings representing the permissions that the
            application is requesting.

            For example,
            "`["MERCHANT_PROFILE_READ","PAYMENTS_READ","BANK_ACCOUNTS_READ"]`".


            The access token returned in the response is granted the permissions

            that comprise the intersection between the requested list of
            permissions and those

            that belong to the provided refresh token.
          nullable: true
        short_lived:
          type: boolean
          description: >-
            A Boolean indicating a request for a short-lived access token.


            The short-lived access token returned in the response expires in 24
            hours.
          nullable: true
        code_verifier:
          type: string
          description: >-
            Must be provided when using the PKCE OAuth flow if `grant_type` is
            set to `authorization_code`. The `code_verifier` is used to verify
            against the

            `code_challenge` associated with the `authorization_code`.
          nullable: true
      example:
        client_id: APPLICATION_ID
        client_secret: APPLICATION_SECRET
        code: CODE_FROM_AUTHORIZE
        grant_type: authorization_code
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/ObtainToken/ObtainTokenRequest.csharp
        java: /sdk_samples/ObtainToken/ObtainTokenRequest.java
        javascript: /sdk_samples/ObtainToken/ObtainTokenRequest.javascript
        php: /sdk_samples/ObtainToken/ObtainTokenRequest.php
        python: /sdk_samples/ObtainToken/ObtainTokenRequest.python
        ruby: /sdk_samples/ObtainToken/ObtainTokenRequest.ruby
    ObtainTokenResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        access_token:
          type: string
          description: >-
            A valid OAuth access token. 

            Provide the access token in a header with every request to Connect
            API

            endpoints. For more information, see [OAuth API:
            Walkthrough](https://developer.squareup.com/docs/oauth-api/walkthrough).
          minLength: 2
          maxLength: 1024
        token_type:
          type: string
          description: This value is always _bearer_.
          minLength: 2
          maxLength: 10
        expires_at:
          type: string
          description: >-
            The date when the `access_token` expires, in [ISO
            8601](http://www.iso.org/iso/home/standards/iso8601.htm) format.
          minLength: 20
          maxLength: 48
        merchant_id:
          type: string
          description: The ID of the authorizing merchant's business.
          minLength: 8
          maxLength: 191
        subscription_id:
          type: string
          description: >-
            __LEGACY FIELD__. The ID of a subscription plan the merchant signed
            up

            for. The ID is only present if the merchant signed up for a
            subscription plan during authorization.
        plan_id:
          type: string
          description: >-
            __LEGACY FIELD__. The ID of the subscription plan the merchant
            signed

            up for. The ID is only present if the merchant signed up for a
            subscription plan during

            authorization.
        id_token:
          type: string
          description: >-
            The OpenID token belonging to this person. This token is only
            present if the

            OPENID scope is included in the authorization request.
          x-release-status: DEPRECATED
        refresh_token:
          type: string
          description: >-
            A refresh token. 

            For more information, see [Refresh, Revoke, and Limit the Scope of
            OAuth
            Tokens](https://developer.squareup.com/docs/oauth-api/refresh-revoke-limit-scope).
          minLength: 2
          maxLength: 1024
        short_lived:
          type: boolean
          description: >-
            A Boolean indicating that the access token is a short-lived access
            token.

            The short-lived access token returned in the response expires in 24
            hours.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        refresh_token_expires_at:
          type: string
          description: >-
            The date when the `refresh_token` expires, in [ISO
            8601](http://www.iso.org/iso/home/standards/iso8601.htm) format.
          minLength: 20
          maxLength: 48
      example:
        access_token: ACCESS_TOKEN
        expires_at: '2006-01-02T15:04:05Z'
        merchant_id: MERCHANT_ID
        refresh_token: REFRESH_TOKEN
        token_type: bearer
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/ObtainToken/ObtainTokenResponse.csharp
        java: /sdk_samples/ObtainToken/ObtainTokenResponse.java
        javascript: /sdk_samples/ObtainToken/ObtainTokenResponse.javascript
        php: /sdk_samples/ObtainToken/ObtainTokenResponse.php
        python: /sdk_samples/ObtainToken/ObtainTokenResponse.python
        ruby: /sdk_samples/ObtainToken/ObtainTokenResponse.ruby
    OfflinePaymentDetails:
      type: object
      description: Details specific to offline payments.
      x-release-status: PUBLIC
      properties:
        client_created_at:
          type: string
          description: >-
            The client-side timestamp of when the offline payment was created,
            in RFC 3339 format.
          maxLength: 32
          readOnly: true
    Order:
      type: object
      description: >-
        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.
      x-release-status: PUBLIC
      required:
        - location_id
      properties:
        id:
          type: string
          description: The order's unique ID.
          readOnly: true
        location_id:
          type: string
          description: The ID of the seller location that this order is associated with.
          minLength: 1
        reference_id:
          type: string
          description: |-
            A client-specified ID to associate an entity in another system
            with this order.
          maxLength: 40
          nullable: true
        source:
          $ref: '#/components/schemas/OrderSource'
          description: The origination details of the order.
          nullable: true
        customer_id:
          type: string
          description: >-
            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).
          maxLength: 191
          x-release-status: BETA
          nullable: true
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItem'
          description: The line items included in the order.
          nullable: true
        taxes:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemTax'
          description: >-
            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.
          nullable: true
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemDiscount'
          description: >-
            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.
          nullable: true
        service_charges:
          type: array
          items:
            $ref: '#/components/schemas/OrderServiceCharge'
          description: A list of service charges applied to the order.
          nullable: true
        fulfillments:
          type: array
          items:
            $ref: '#/components/schemas/Fulfillment'
          description: >-
            Details about order fulfillment.


            Orders can only be created with at most one fulfillment. However,
            orders returned

            by the API might contain multiple fulfillments.
          nullable: true
        returns:
          type: array
          items:
            $ref: '#/components/schemas/OrderReturn'
          description: >-
            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.
          readOnly: true
          x-release-status: BETA
        return_amounts:
          $ref: '#/components/schemas/OrderMoneyAmounts'
          description: The rollup of the returned money amounts.
          readOnly: true
          x-release-status: BETA
        net_amounts:
          $ref: '#/components/schemas/OrderMoneyAmounts'
          description: The net money amounts (sale money - return money).
          readOnly: true
          x-release-status: BETA
        rounding_adjustment:
          $ref: '#/components/schemas/OrderRoundingAdjustment'
          description: >-
            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.
          readOnly: true
          x-release-status: BETA
        tenders:
          type: array
          items:
            $ref: '#/components/schemas/Tender'
          description: The tenders that were used to pay for the order.
          readOnly: true
          x-release-status: BETA
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
          description: The refunds that are part of this order.
          readOnly: true
          x-release-status: BETA
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            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).
          x-release-status: BETA
          nullable: true
        created_at:
          type: string
          description: >-
            The timestamp for when the order was created, at server side, in RFC
            3339 format (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp for when the order was last updated, at server side,
            in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        closed_at:
          type: string
          description: >-
            The timestamp for when the order reached a terminal
            [state](entity:OrderState), in RFC 3339 format (for example
            "2016-09-04T23:59:33.123Z").
          readOnly: true
        state:
          $ref: '#/components/schemas/OrderState'
          description: |-
            The current state of the order.
            See [OrderState](#type-orderstate) for possible values
          nullable: true
        version:
          type: integer
          description: >-
            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).
          x-release-status: BETA
        total_money:
          $ref: '#/components/schemas/Money'
          description: The total amount of money to collect for the order.
          readOnly: true
        total_tax_money:
          $ref: '#/components/schemas/Money'
          description: The total amount of tax money to collect for the order.
          readOnly: true
        total_discount_money:
          $ref: '#/components/schemas/Money'
          description: The total amount of discount money to collect for the order.
          readOnly: true
        total_tip_money:
          $ref: '#/components/schemas/Money'
          description: The total amount of tip money to collect for the order.
          readOnly: true
        total_service_charge_money:
          $ref: '#/components/schemas/Money'
          description: >-
            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.
          readOnly: true
        ticket_name:
          type: string
          description: >-
            A short-term identifier for the order (such as a customer first
            name,

            table number, or auto-generated order number that resets daily).
          maxLength: 30
          x-release-status: BETA
          nullable: true
        pricing_options:
          $ref: '#/components/schemas/OrderPricingOptions'
          description: >-
            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).
          nullable: true
        rewards:
          type: array
          items:
            $ref: '#/components/schemas/OrderReward'
          description: A set-like list of Rewards that have been added to the Order.
          readOnly: true
          x-release-status: BETA
        net_amount_due_money:
          $ref: '#/components/schemas/Money'
          description: The net amount of money due on the order.
          readOnly: true
    OrderCreated:
      type: object
      x-release-status: BETA
      properties:
        order_id:
          type: string
          description: The order's unique ID.
          nullable: true
        version:
          type: integer
          description: >-
            The version number, which is incremented each time an update is
            committed to the order.

            Orders that were 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)
        location_id:
          type: string
          description: The ID of the seller location that this order is associated with.
          nullable: true
        state:
          $ref: '#/components/schemas/OrderState'
          description: |-
            The state of the order.
            See [OrderState](#type-orderstate) for possible values
          nullable: true
        created_at:
          type: string
          description: The timestamp for when the order was created, in RFC 3339 format.
          readOnly: true
    OrderCreatedObject:
      type: object
      x-release-status: BETA
      properties:
        order_created:
          $ref: '#/components/schemas/OrderCreated'
          description: Information about the created order.
          nullable: true
    OrderEntry:
      type: object
      description: >-
        A lightweight description of an [order](entity:Order) that is returned
        when

        `returned_entries` is `true` on a
        [SearchOrdersRequest](api-endpoint:Orders-SearchOrders).
      x-release-status: PUBLIC
      properties:
        order_id:
          type: string
          description: The ID of the order.
          nullable: true
        version:
          type: integer
          description: >-
            The version number, which is incremented each time an update is
            committed to the order.

            Orders that were 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)
          readOnly: true
          x-release-status: BETA
        location_id:
          type: string
          description: The location ID the order belongs to.
          nullable: true
    OrderFulfillment:
      type: object
      description: >-
        Contains details about how to fulfill this order.

        Orders can only be created with at most one fulfillment using the API.

        However, orders returned by the Orders API might contain multiple
        fulfillments because sellers can create multiple fulfillments using
        Square products such as Square Online.
      x-release-status: PUBLIC
      properties:
        uid:
          type: string
          description: A unique ID that identifies the fulfillment only within this order.
          maxLength: 60
          x-release-status: BETA
          nullable: true
        type:
          $ref: '#/components/schemas/OrderFulfillmentType'
          description: >-
            The type of the fulfillment.

            See [OrderFulfillmentType](#type-orderfulfillmenttype) for possible
            values
          nullable: true
        state:
          $ref: '#/components/schemas/OrderFulfillmentState'
          description: >-
            The state of the fulfillment.

            See [OrderFulfillmentState](#type-orderfulfillmentstate) for
            possible values
          nullable: true
        line_item_application:
          $ref: '#/components/schemas/OrderFulfillmentFulfillmentLineItemApplication'
          description: >-
            Describes what order line items this fulfillment applies to.

            It can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment
            entries.

            See
            [OrderFulfillmentFulfillmentLineItemApplication](#type-orderfulfillmentfulfillmentlineitemapplication)
            for possible values
          readOnly: true
          x-release-status: BETA
        entries:
          type: array
          items:
            $ref: '#/components/schemas/OrderFulfillmentFulfillmentEntry'
          description: >-
            A list of entries pertaining to the fulfillment of an order. Each
            entry must reference

            a valid `uid` for an order line item in the `line_item_uid` field,
            as well as a `quantity` to

            fulfill.

            Multiple entries can reference the same line item `uid`, as long as
            the total quantity among

            all fulfillment entries referencing a single line item does not
            exceed the quantity of the

            order's line item itself.

            An order cannot be marked as `COMPLETED` before all fulfillments are
            `COMPLETED`,

            `CANCELED`, or `FAILED`. Fulfillments can be created and completed
            independently

            before order completion.
          readOnly: true
          x-release-status: BETA
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Application-defined data attached to this fulfillment. 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).
          x-release-status: BETA
          nullable: true
        pickup_details:
          $ref: '#/components/schemas/OrderFulfillmentPickupDetails'
          description: >-
            Contains details for a pickup fulfillment. These details are
            required when the fulfillment

            type is `PICKUP`.
          nullable: true
        shipment_details:
          $ref: '#/components/schemas/OrderFulfillmentShipmentDetails'
          description: >-
            Contains details for a shipment fulfillment. These details are
            required when the fulfillment type

            is `SHIPMENT`.

            A shipment fulfillment's relationship to fulfillment `state`:

            `PROPOSED`: A shipment is requested.

            `RESERVED`: Fulfillment in progress. Shipment processing.

            `PREPARED`: Shipment packaged. Shipping label created.

            `COMPLETED`: Package has been shipped.

            `CANCELED`: Shipment has been canceled.

            `FAILED`: Shipment has failed.
          x-release-status: BETA
          nullable: true
        delivery_details:
          $ref: '#/components/schemas/OrderFulfillmentDeliveryDetails'
          description: Describes delivery details of an order fulfillment.
          x-release-status: BETA
          nullable: true
    OrderFulfillmentDeliveryDetails:
      type: object
      description: Describes delivery details of an order fulfillment.
      x-release-status: BETA
      properties:
        recipient:
          $ref: '#/components/schemas/OrderFulfillmentRecipient'
          description: The contact information for the person to receive the fulfillment.
          nullable: true
        schedule_type:
          $ref: '#/components/schemas/OrderFulfillmentDeliveryDetailsScheduleType'
          description: >-
            Indicates the fulfillment delivery schedule type. If `SCHEDULED`,
            then

            `deliver_at` is required. If `ASAP`, then `prep_time_duration` is
            required. The default is `SCHEDULED`.

            See
            [OrderFulfillmentDeliveryDetailsScheduleType](#type-orderfulfillmentdeliverydetailsscheduletype)
            for possible values
          nullable: true
        placed_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was placed.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").

            Must be in RFC 3339 timestamp format, e.g.,
            "2016-09-04T23:59:33.123Z".
          readOnly: true
        deliver_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            that represents the start of the delivery period.

            When the fulfillment `schedule_type` is `ASAP`, the field is
            automatically

            set to the current time plus the `prep_time_duration`.

            Otherwise, the application can set this field while the fulfillment
            `state` is

            `PROPOSED`, `RESERVED`, or `PREPARED` (any time before the

            terminal state such as `COMPLETED`, `CANCELED`, and `FAILED`).


            The timestamp must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          nullable: true
        prep_time_duration:
          type: string
          description: >-
            The duration of time it takes to prepare and deliver this
            fulfillment.

            The duration must be in RFC 3339 format (for example, "P1W3D").
          nullable: true
        delivery_window_duration:
          type: string
          description: >-
            The time period after `deliver_at` in which to deliver the order.

            Applications can set this field when the fulfillment `state` is

            `PROPOSED`, `RESERVED`, or `PREPARED` (any time before the terminal
            state

            such as `COMPLETED`, `CANCELED`, and `FAILED`).

            The duration must be in RFC 3339 format (for example, "P1W3D").
          nullable: true
        note:
          type: string
          description: >-
            Provides additional instructions about the delivery fulfillment.

            It is displayed in the Square Point of Sale application and set by
            the API.
          maxLength: 550
          nullable: true
        completed_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicates when the seller completed the fulfillment.

            This field is automatically set when  fulfillment `state` changes to
            `COMPLETED`.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          nullable: true
        in_progress_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicates when the seller started processing the fulfillment.

            This field is automatically set when the fulfillment `state` changes
            to `RESERVED`.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          readOnly: true
        rejected_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was rejected. This field is

            automatically set when the fulfillment `state` changes to `FAILED`.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          readOnly: true
        ready_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the seller marked the fulfillment as ready for

            courier pickup. This field is automatically set when the fulfillment
            `state` changes

            to PREPARED.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          readOnly: true
        delivered_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was delivered to the recipient.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          readOnly: true
        canceled_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was canceled. This field is
            automatically

            set when the fulfillment `state` changes to `CANCELED`.


            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          readOnly: true
        cancel_reason:
          type: string
          description: 'The delivery cancellation reason. Max length: 100 characters.'
          maxLength: 100
          nullable: true
        courier_pickup_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when an order can be picked up by the courier for
            delivery.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          nullable: true
        courier_pickup_window_duration:
          type: string
          description: >-
            The time period after `courier_pickup_at` in which the courier
            should pick up the order.

            The duration must be in RFC 3339 format (for example, "P1W3D").
          nullable: true
        is_no_contact_delivery:
          type: boolean
          description: Whether the delivery is preferred to be no contact.
          nullable: true
        dropoff_notes:
          type: string
          description: >-
            A note to provide additional instructions about how to deliver the
            order.
          maxLength: 550
          nullable: true
        courier_provider_name:
          type: string
          description: The name of the courier provider.
          maxLength: 255
          nullable: true
        courier_support_phone_number:
          type: string
          description: The support phone number of the courier.
          maxLength: 17
          nullable: true
        square_delivery_id:
          type: string
          description: The identifier for the delivery created by Square.
          maxLength: 50
          nullable: true
        external_delivery_id:
          type: string
          description: >-
            The identifier for the delivery created by the third-party courier
            service.
          maxLength: 50
          nullable: true
        managed_delivery:
          type: boolean
          description: >-
            The flag to indicate the delivery is managed by a third party (ie
            DoorDash), which means

            we may not receive all recipient information for PII purposes.
          nullable: true
    OrderFulfillmentDeliveryDetailsScheduleType:
      type: string
      enum:
        - SCHEDULED
        - ASAP
      x-enum-elements:
        - name: SCHEDULED
          description: Indicates the fulfillment to deliver at a scheduled deliver time.
        - name: ASAP
          description: >-
            Indicates that the fulfillment to deliver as soon as possible and
            should be prepared

            immediately.
      description: The schedule type of the delivery fulfillment.
      x-release-status: BETA
    OrderFulfillmentFulfillmentEntry:
      type: object
      description: >-
        Links an order line item to a fulfillment. Each entry must reference

        a valid `uid` for an order line item in the `line_item_uid` field, as
        well as a `quantity` to

        fulfill.
      x-release-status: BETA
      required:
        - line_item_uid
        - quantity
      properties:
        uid:
          type: string
          description: >-
            A unique ID that identifies the fulfillment entry only within this
            order.
          maxLength: 60
          nullable: true
        line_item_uid:
          type: string
          description: The `uid` from the order line item.
          minLength: 1
        quantity:
          type: string
          description: >-
            The quantity of the line item being fulfilled, formatted as a
            decimal number.

            For example, `"3"`.

            Fulfillments for line items with a `quantity_unit` can have
            non-integer quantities.

            For example, `"1.70000"`.
          minLength: 1
          maxLength: 12
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Application-defined data attached to this fulfillment entry.
            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).
          nullable: true
    OrderFulfillmentFulfillmentLineItemApplication:
      type: string
      enum:
        - ALL
        - ENTRY_LIST
      x-enum-elements:
        - name: ALL
          description: If `ALL`, `entries` must be unset.
        - name: ENTRY_LIST
          description: If `ENTRY_LIST`, supply a list of `entries`.
      description: >-
        The `line_item_application` describes what order line items this
        fulfillment applies

        to. It can be `ALL` or `ENTRY_LIST` with a supplied list of fulfillment
        entries.
      x-release-status: BETA
    OrderFulfillmentPickupDetails:
      type: object
      description: Contains details necessary to fulfill a pickup order.
      x-release-status: PUBLIC
      properties:
        recipient:
          $ref: '#/components/schemas/OrderFulfillmentRecipient'
          description: >-
            Information about the person to pick up this fulfillment from a
            physical

            location.
          nullable: true
        expires_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when this fulfillment expires if it is not marked in
            progress. The timestamp must be

            in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z"). The
            expiration time can only be set

            up to 7 days in the future. If `expires_at` is not set, any new
            payments attached to the order

            are automatically completed.
          nullable: true
        auto_complete_duration:
          type: string
          description: >-
            The duration of time after which an in progress pickup fulfillment
            is automatically moved

            to the `COMPLETED` state. The duration must be in RFC 3339 format
            (for example, "P1W3D").


            If not set, this pickup fulfillment remains in progress until it is
            canceled or completed.
          nullable: true
        schedule_type:
          $ref: '#/components/schemas/OrderFulfillmentPickupDetailsScheduleType'
          description: >-
            The schedule type of the pickup fulfillment. Defaults to
            `SCHEDULED`.

            See
            [OrderFulfillmentPickupDetailsScheduleType](#type-orderfulfillmentpickupdetailsscheduletype)
            for possible values
          nullable: true
        pickup_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            that represents the start of the pickup window. Must be in RFC 3339
            timestamp format, e.g.,

            "2016-09-04T23:59:33.123Z".

            For fulfillments with the schedule type `ASAP`, this is
            automatically set

            to the current time plus the expected duration to prepare the
            fulfillment.
          nullable: true
        pickup_window_duration:
          type: string
          description: >-
            The window of time in which the order should be picked up after the
            `pickup_at` timestamp.

            Must be in RFC 3339 duration format, e.g., "P1W3D". Can be used as
            an

            informational guideline for merchants.
          nullable: true
        prep_time_duration:
          type: string
          description: |-
            The duration of time it takes to prepare this fulfillment.
            The duration must be in RFC 3339 format (for example, "P1W3D").
          nullable: true
        note:
          type: string
          description: >-
            A note to provide additional instructions about the pickup

            fulfillment displayed in the Square Point of Sale application and
            set by the API.
          maxLength: 500
          nullable: true
        placed_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was placed. The timestamp must be in
            RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        accepted_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was marked in progress. The
            timestamp must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        rejected_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was rejected. The timestamp must be
            in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        ready_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment is marked as ready for pickup. The
            timestamp must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        expired_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment expired. The timestamp must be in
            RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        picked_up_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was picked up by the recipient. The
            timestamp must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        canceled_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the fulfillment was canceled. The timestamp must be
            in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        cancel_reason:
          type: string
          description: >-
            A description of why the pickup was canceled. The maximum length:
            100 characters.
          maxLength: 100
          nullable: true
        is_curbside_pickup:
          type: boolean
          description: >-
            If set to `true`, indicates that this pickup order is for curbside
            pickup, not in-store pickup.
          x-release-status: BETA
          nullable: true
        curbside_pickup_details:
          $ref: >-
            #/components/schemas/OrderFulfillmentPickupDetailsCurbsidePickupDetails
          description: >-
            Specific details for curbside pickup. These details can only be
            populated if `is_curbside_pickup` is set to `true`.
          x-release-status: BETA
          nullable: true
    OrderFulfillmentPickupDetailsCurbsidePickupDetails:
      type: object
      description: Specific details for curbside pickup.
      x-release-status: BETA
      properties:
        curbside_details:
          type: string
          description: >-
            Specific details for curbside pickup, such as parking number and
            vehicle model.
          maxLength: 250
          nullable: true
        buyer_arrived_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the buyer arrived and is waiting for pickup. The
            timestamp must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          nullable: true
    OrderFulfillmentPickupDetailsScheduleType:
      type: string
      enum:
        - SCHEDULED
        - ASAP
      x-enum-elements:
        - name: SCHEDULED
          description: >-
            Indicates that the fulfillment will be picked up at a scheduled
            pickup time.
        - name: ASAP
          description: >-
            Indicates that the fulfillment will be picked up as soon as possible
            and

            should be prepared immediately.
      description: The schedule type of the pickup fulfillment.
      x-release-status: PUBLIC
    OrderFulfillmentRecipient:
      type: object
      description: Information about the fulfillment recipient.
      x-release-status: PUBLIC
      properties:
        customer_id:
          type: string
          description: >-
            The ID of the customer associated with the fulfillment.

            If `customer_id` is provided, the fulfillment recipient's
            `display_name`,

            `email_address`, and `phone_number` are automatically populated from
            the

            targeted customer profile. If these fields are set in the request,
            the request

            values override the information from the customer profile. If the

            targeted customer profile does not contain the necessary information
            and

            these fields are left unset, the request results in an error.
          maxLength: 191
          nullable: true
        display_name:
          type: string
          description: >-
            The display name of the fulfillment recipient. This field is
            required.

            If provided, the display name overrides the corresponding customer
            profile value

            indicated by `customer_id`.
          maxLength: 255
          nullable: true
        email_address:
          type: string
          description: >-
            The email address of the fulfillment recipient.

            If provided, the email address overrides the corresponding customer
            profile value

            indicated by `customer_id`.
          maxLength: 255
          nullable: true
        phone_number:
          type: string
          description: >-
            The phone number of the fulfillment recipient. This field is
            required.

            If provided, the phone number overrides the corresponding customer
            profile value

            indicated by `customer_id`.
          maxLength: 17
          nullable: true
        address:
          $ref: '#/components/schemas/Address'
          description: >-
            The address of the fulfillment recipient. This field is required.

            If provided, the address overrides the corresponding customer
            profile value

            indicated by `customer_id`.
          x-release-status: BETA
          nullable: true
    OrderFulfillmentShipmentDetails:
      type: object
      description: Contains the details necessary to fulfill a shipment order.
      x-release-status: BETA
      properties:
        recipient:
          $ref: '#/components/schemas/OrderFulfillmentRecipient'
          description: Information about the person to receive this shipment fulfillment.
          nullable: true
        carrier:
          type: string
          description: >-
            The shipping carrier being used to ship this fulfillment (such as
            UPS, FedEx, or USPS).
          maxLength: 50
          nullable: true
        shipping_note:
          type: string
          description: A note with additional information for the shipping carrier.
          maxLength: 500
          nullable: true
        shipping_type:
          type: string
          description: >-
            A description of the type of shipping product purchased from the
            carrier

            (such as First Class, Priority, or Express).
          maxLength: 50
          nullable: true
        tracking_number:
          type: string
          description: >-
            The reference number provided by the carrier to track the shipment's
            progress.
          maxLength: 100
          nullable: true
        tracking_url:
          type: string
          description: A link to the tracking webpage on the carrier's website.
          maxLength: 2000
          nullable: true
        placed_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the shipment was requested. The timestamp must be in
            RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        in_progress_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when this fulfillment was moved to the `RESERVED` state,
            which  indicates that preparation

            of this shipment has begun. The timestamp must be in RFC 3339 format
            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        packaged_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when this fulfillment was moved to the `PREPARED` state,
            which indicates that the

            fulfillment is packaged. The timestamp must be in RFC 3339 format
            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        expected_shipped_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the shipment is expected to be delivered to the
            shipping carrier.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          nullable: true
        shipped_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when this fulfillment was moved to the `COMPLETED` state,
            which indicates that

            the fulfillment has been given to the shipping carrier. The
            timestamp must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        canceled_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating the shipment was canceled.

            The timestamp must be in RFC 3339 format (for example,
            "2016-09-04T23:59:33.123Z").
          nullable: true
        cancel_reason:
          type: string
          description: A description of why the shipment was canceled.
          maxLength: 100
          nullable: true
        failed_at:
          type: string
          description: >-
            The
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)

            indicating when the shipment failed to be completed. The timestamp
            must be in RFC 3339 format

            (for example, "2016-09-04T23:59:33.123Z").
          readOnly: true
        failure_reason:
          type: string
          description: A description of why the shipment failed to be completed.
          maxLength: 100
          nullable: true
    OrderFulfillmentState:
      type: string
      enum:
        - PROPOSED
        - RESERVED
        - PREPARED
        - COMPLETED
        - CANCELED
        - FAILED
      x-enum-elements:
        - name: PROPOSED
          description: Indicates that the fulfillment has been proposed.
        - name: RESERVED
          description: Indicates that the fulfillment has been reserved.
        - name: PREPARED
          description: Indicates that the fulfillment has been prepared.
        - name: COMPLETED
          description: Indicates that the fulfillment was successfully completed.
        - name: CANCELED
          description: Indicates that the fulfillment was canceled.
        - name: FAILED
          description: >-
            Indicates that the fulfillment failed to be completed, but was not
            explicitly

            canceled.
      description: The current state of this fulfillment.
      x-release-status: PUBLIC
    OrderFulfillmentType:
      type: string
      enum:
        - PICKUP
        - SHIPMENT
        - DELIVERY
      x-enum-elements:
        - name: PICKUP
          description: >-
            A recipient to pick up the fulfillment from a physical
            [location](entity:Location).
        - name: SHIPMENT
          description: A shipping carrier to ship the fulfillment.
        - name: DELIVERY
          description: A courier to deliver the fulfillment.
      description: The type of fulfillment.
      x-release-status: PUBLIC
    OrderFulfillmentUpdated:
      type: object
      x-release-status: BETA
      properties:
        order_id:
          type: string
          description: The order's unique ID.
          nullable: true
        version:
          type: integer
          description: >-
            The version number, which is incremented each time an update is
            committed to the order.

            Orders that were 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)
        location_id:
          type: string
          description: The ID of the seller location that this order is associated with.
          nullable: true
        state:
          $ref: '#/components/schemas/OrderState'
          description: |-
            The state of the order.
            See [OrderState](#type-orderstate) for possible values
          nullable: true
        created_at:
          type: string
          description: The timestamp for when the order was created, in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp for when the order was last updated, in RFC 3339
            format.
          readOnly: true
        fulfillment_update:
          type: array
          items:
            $ref: '#/components/schemas/OrderFulfillmentUpdatedUpdate'
          description: The fulfillments that were updated with this version change.
          nullable: true
    OrderFulfillmentUpdatedObject:
      type: object
      x-release-status: BETA
      properties:
        order_fulfillment_updated:
          $ref: '#/components/schemas/OrderFulfillmentUpdated'
          description: Information about the updated order fulfillment.
          nullable: true
    OrderFulfillmentUpdatedUpdate:
      type: object
      description: Information about fulfillment updates.
      x-release-status: BETA
      properties:
        fulfillment_uid:
          type: string
          description: A unique ID that identifies the fulfillment only within this order.
          nullable: true
        old_state:
          $ref: '#/components/schemas/FulfillmentState'
          description: >-
            The state of the fulfillment before the change.

            The state is not populated if the fulfillment is created with this
            new `Order` version.
          nullable: true
        new_state:
          $ref: '#/components/schemas/FulfillmentState'
          description: >-
            The state of the fulfillment after the change. The state might be
            equal to `old_state` if a non-state

            field was changed on the fulfillment (such as the tracking number).
          nullable: true
    OrderLineItem:
      type: object
      description: |-
        Represents a line item in an order. Each line item describes a different
        product to purchase, with its own quantity and price details.
      x-release-status: PUBLIC
      required:
        - quantity
      properties:
        uid:
          type: string
          description: A unique ID that identifies the line item only within this order.
          maxLength: 60
          x-release-status: BETA
          nullable: true
        name:
          type: string
          description: The name of the line item.
          maxLength: 512
          nullable: true
        quantity:
          type: string
          description: >-
            The count, or measurement, of a line item being purchased:


            If `quantity` is a whole number, and `quantity_unit` is not
            specified, then `quantity` denotes an item count.  For example: `3`
            apples.


            If `quantity` is a whole or decimal number, and `quantity_unit` is
            also specified, then `quantity` denotes a measurement.  For example:
            `2.25` pounds of broccoli.


            For more information, see [Specify item quantity and measurement
            unit](https://developer.squareup.com/docs/orders-api/create-orders#specify-item-quantity-and-measurement-unit).


            Line items with a quantity of `0` are automatically removed

            when paying for or otherwise completing the order.
          minLength: 1
          maxLength: 12
        quantity_unit:
          $ref: '#/components/schemas/OrderQuantityUnit'
          description: >-
            The measurement unit and decimal precision that this line item's
            quantity is measured in.
          nullable: true
        note:
          type: string
          description: An optional note associated with the line item.
          maxLength: 2000
          nullable: true
        catalog_object_id:
          type: string
          description: >-
            The [CatalogItemVariation](entity:CatalogItemVariation) ID applied
            to this line item.
          maxLength: 192
          nullable: true
        catalog_version:
          type: integer
          description: The version of the catalog object that this line item references.
          format: int64
          nullable: true
        variation_name:
          type: string
          description: The name of the variation applied to this line item.
          maxLength: 400
          nullable: true
        item_type:
          $ref: '#/components/schemas/OrderLineItemItemType'
          description: >-
            The type of line item: an itemized sale, a non-itemized sale (custom
            amount), or the

            activation or reloading of a gift card.

            See [OrderLineItemItemType](#type-orderlineitemitemtype) for
            possible values
          nullable: true
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Application-defined data attached to this line item. 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).
          x-release-status: BETA
          nullable: true
        modifiers:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemModifier'
          description: >-
            The [CatalogModifier](entity:CatalogModifier)s applied to this line
            item.
          nullable: true
        applied_taxes:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemAppliedTax'
          description: >-
            The list of references to taxes applied to this line item. Each

            `OrderLineItemAppliedTax` has a `tax_uid` that references the `uid`
            of a

            top-level `OrderLineItemTax` applied to the line item. On reads, the

            amount applied is populated.


            An `OrderLineItemAppliedTax` is automatically created on every line

            item for all `ORDER` scoped taxes added to the order.
            `OrderLineItemAppliedTax`

            records for `LINE_ITEM` scoped taxes must be added in requests for
            the tax

            to apply to any line items.


            To change the amount of a tax, modify the referenced top-level tax.
          x-release-status: BETA
          nullable: true
        applied_discounts:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemAppliedDiscount'
          description: >-
            The list of references to discounts applied to this line item. Each

            `OrderLineItemAppliedDiscount` has a `discount_uid` that references
            the `uid` of a top-level

            `OrderLineItemDiscounts` applied to the line item. On reads, the
            amount

            applied is populated.


            An `OrderLineItemAppliedDiscount` is automatically created on every
            line item for all

            `ORDER` scoped discounts that are added to the order.
            `OrderLineItemAppliedDiscount` records

            for `LINE_ITEM` scoped discounts must be added in requests for the
            discount to apply to any

            line items.


            To change the amount of a discount, modify the referenced top-level
            discount.
          x-release-status: BETA
          nullable: true
        applied_service_charges:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemAppliedServiceCharge'
          description: >-
            The list of references to service charges applied to this line item.
            Each

            `OrderLineItemAppliedServiceCharge` has a `service_charge_id` that
            references the `uid` of a

            top-level `OrderServiceCharge` applied to the line item. On reads,
            the amount applied is

            populated.


            To change the amount of a service charge, modify the referenced
            top-level service charge.
          x-release-status: BETA
          nullable: true
        base_price_money:
          $ref: '#/components/schemas/Money'
          description: The base price for a single unit of the line item.
          nullable: true
        variation_total_price_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The total price of all item variations sold in this line item.

            The price is calculated as `base_price_money` multiplied by
            `quantity`.

            It does not include modifiers.
          readOnly: true
        gross_sales_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money made in gross sales for this line item.

            The amount is calculated as the sum of the variation's total price
            and each modifier's total price.

            For inclusive tax items in the US, Canada, and Japan, tax is
            deducted from `gross_sales_money`. For Europe and

            Australia, inclusive tax remains as part of the gross sale
            calculation.
          readOnly: true
        total_tax_money:
          $ref: '#/components/schemas/Money'
          description: The total amount of tax money to collect for the line item.
          readOnly: true
        total_discount_money:
          $ref: '#/components/schemas/Money'
          description: The total amount of discount money to collect for the line item.
          readOnly: true
        total_money:
          $ref: '#/components/schemas/Money'
          description: The total amount of money to collect for this line item.
          readOnly: true
        pricing_blocklists:
          $ref: '#/components/schemas/OrderLineItemPricingBlocklists'
          description: >-
            Describes pricing adjustments that are blocked from automatic

            application to a line item. For more information, see

            [Apply Taxes and
            Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts).
          x-release-status: BETA
          nullable: true
        total_service_charge_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The total amount of apportioned service charge money to collect for
            the line item.
          readOnly: true
          x-release-status: BETA
    OrderLineItemAppliedDiscount:
      type: object
      description: >-
        Represents an applied portion of a discount to a line item in an order.


        Order scoped discounts have automatically applied discounts present for
        each line item.

        Line-item scoped discounts must have applied discounts added manually
        for any applicable line

        items. The corresponding applied money is automatically computed based
        on participating

        line items.
      x-release-status: BETA
      required:
        - discount_uid
      properties:
        uid:
          type: string
          description: >-
            A unique ID that identifies the applied discount only within this
            order.
          maxLength: 60
          nullable: true
        discount_uid:
          type: string
          description: >-
            The `uid` of the discount that the applied discount represents. It
            must

            reference a discount present in the `order.discounts` field.


            This field is immutable. To change which discounts apply to a line
            item,

            you must delete the discount and re-add it as a new
            `OrderLineItemAppliedDiscount`.
          minLength: 1
          maxLength: 60
        applied_money:
          $ref: '#/components/schemas/Money'
          description: The amount of money applied by the discount to the line item.
          readOnly: true
    OrderLineItemAppliedServiceCharge:
      type: object
      x-release-status: BETA
      required:
        - service_charge_uid
      properties:
        uid:
          type: string
          description: >-
            A unique ID that identifies the applied service charge only within
            this order.
          maxLength: 60
          nullable: true
        service_charge_uid:
          type: string
          description: >-
            The `uid` of the service charge that the applied service charge
            represents. It must

            reference a service charge present in the `order.service_charges`
            field.


            This field is immutable. To change which service charges apply to a
            line item,

            delete and add a new `OrderLineItemAppliedServiceCharge`.
          minLength: 1
          maxLength: 60
        applied_money:
          $ref: '#/components/schemas/Money'
          description: The amount of money applied by the service charge to the line item.
          readOnly: true
    OrderLineItemAppliedTax:
      type: object
      description: >-
        Represents an applied portion of a tax to a line item in an order.


        Order-scoped taxes automatically include the applied taxes in each line
        item.

        Line item taxes must be referenced from any applicable line items.

        The corresponding applied money is automatically computed, based on the

        set of participating line items.
      x-release-status: BETA
      required:
        - tax_uid
      properties:
        uid:
          type: string
          description: A unique ID that identifies the applied tax only within this order.
          maxLength: 60
          nullable: true
        tax_uid:
          type: string
          description: >-
            The `uid` of the tax for which this applied tax represents. It must
            reference

            a tax present in the `order.taxes` field.


            This field is immutable. To change which taxes apply to a line item,
            delete and add a new

            `OrderLineItemAppliedTax`.
          minLength: 1
          maxLength: 60
        applied_money:
          $ref: '#/components/schemas/Money'
          description: The amount of money applied by the tax to the line item.
          readOnly: true
    OrderLineItemDiscount:
      type: object
      description: >-
        Represents a discount that applies to one or more line items in an

        order.


        Fixed-amount, order-scoped discounts are distributed across all non-zero
        line item totals.

        The amount distributed to each line item is relative to the

        amount contributed by the item to the order subtotal.
      x-release-status: PUBLIC
      properties:
        uid:
          type: string
          description: A unique ID that identifies the discount only within this order.
          maxLength: 60
          x-release-status: BETA
          nullable: true
        catalog_object_id:
          type: string
          description: >-
            The catalog object ID referencing
            [CatalogDiscount](entity:CatalogDiscount).
          maxLength: 192
          nullable: true
        catalog_version:
          type: integer
          description: The version of the catalog object that this discount references.
          format: int64
          nullable: true
        name:
          type: string
          description: The discount's name.
          maxLength: 255
          nullable: true
        type:
          $ref: '#/components/schemas/OrderLineItemDiscountType'
          description: >-
            The type of the discount.


            Discounts that do not reference a catalog object ID must have a type
            of

            `FIXED_PERCENTAGE` or `FIXED_AMOUNT`.

            See [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for
            possible values
          nullable: true
        percentage:
          type: string
          description: >-
            The percentage of the discount, as a string representation of a
            decimal number.

            A value of `7.25` corresponds to a percentage of 7.25%.


            `percentage` is not set for amount-based discounts.
          maxLength: 10
          nullable: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The total declared monetary amount of the discount.

            `amount_money` is not set for percentage-based discounts.
          nullable: true
        applied_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of discount actually applied to the line item.


            The amount represents the amount of money applied as a line-item
            scoped discount.

            When an amount-based discount is scoped to the entire order, the
            value

            of `applied_money` is different than `amount_money` because the
            total

            amount of the discount is distributed across all line items.
          nullable: true
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Application-defined data attached to this discount. 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).
          x-release-status: BETA
          nullable: true
        scope:
          $ref: '#/components/schemas/OrderLineItemDiscountScope'
          description: >-
            Indicates the level at which the discount applies. For `ORDER`
            scoped discounts,

            Square generates references in `applied_discounts` on all order line
            items that do

            not have them. For `LINE_ITEM` scoped discounts, the discount only
            applies to line items

            with a discount reference in their `applied_discounts` field.


            This field is immutable. To change the scope of a discount, you must
            delete

            the discount and re-add it as a new discount.

            See [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope)
            for possible values
          nullable: true
        reward_ids:
          type: array
          items:
            type: string
          description: >-
            The reward IDs corresponding to this discount. The application and

            specification of discounts that have `reward_ids` are completely
            controlled by the backing

            criteria corresponding to the reward tiers of the rewards that are
            added to the order

            through the Loyalty API. To manually unapply discounts that are the
            result of added rewards,

            the rewards must be removed from the order through the Loyalty API.
          readOnly: true
          x-release-status: BETA
        pricing_rule_id:
          type: string
          description: >-
            The object ID of a [pricing rule](entity:CatalogPricingRule) to be
            applied

            automatically to this discount. The specification and application of
            the discounts, to

            which a `pricing_rule_id` is assigned, are completely controlled by
            the corresponding

            pricing rule.
          readOnly: true
    OrderLineItemDiscountScope:
      type: string
      enum:
        - OTHER_DISCOUNT_SCOPE
        - LINE_ITEM
        - ORDER
      x-enum-elements:
        - name: OTHER_DISCOUNT_SCOPE
          description: >-
            Used for reporting only.

            The original transaction discount scope is currently not supported
            by the API.
        - name: LINE_ITEM
          description: |-
            The discount should be applied to only line items specified by
            `OrderLineItemAppliedDiscount` reference records.
        - name: ORDER
          description: The discount should be applied to the entire order.
      description: Indicates whether this is a line-item or order-level discount.
      x-release-status: PUBLIC
    OrderLineItemDiscountType:
      type: string
      enum:
        - UNKNOWN_DISCOUNT
        - FIXED_PERCENTAGE
        - FIXED_AMOUNT
        - VARIABLE_PERCENTAGE
        - VARIABLE_AMOUNT
      x-enum-elements:
        - name: UNKNOWN_DISCOUNT
          description: >-
            Used for reporting only.

            The original transaction discount type is currently not supported by
            the API.
        - name: FIXED_PERCENTAGE
          description: >-
            Apply the discount as a fixed percentage (such as 5%) off the item
            price.
        - name: FIXED_AMOUNT
          description: >-
            Apply the discount as a fixed monetary value (such as $1.00) off the
            item price.
        - name: VARIABLE_PERCENTAGE
          description: |-
            Apply the discount as a variable percentage based on the item
            price.

            The specific discount percentage of a `VARIABLE_PERCENTAGE` discount
            is assigned at the time of the purchase.
        - name: VARIABLE_AMOUNT
          description: |-
            Apply the discount as a variable amount based on the item price.

            The specific discount amount of a `VARIABLE_AMOUNT` discount
            is assigned at the time of the purchase.
      description: >-
        Indicates how the discount is applied to the associated line item or
        order.
      x-release-status: PUBLIC
    OrderLineItemItemType:
      type: string
      enum:
        - ITEM
        - CUSTOM_AMOUNT
        - GIFT_CARD
      x-enum-elements:
        - name: ITEM
          description: Indicates that the line item is an itemized sale.
        - name: CUSTOM_AMOUNT
          description: Indicates that the line item is a non-itemized sale.
        - name: GIFT_CARD
          description: >-
            Indicates that the line item is a gift card sale. Gift cards sold
            through

            the Orders API are sold in an unactivated state and can be activated
            through the

            Gift Cards API using the line item `uid`.
      description: Represents the line item type.
      x-release-status: BETA
    OrderLineItemModifier:
      type: object
      description: A [CatalogModifier](entity:CatalogModifier).
      x-release-status: PUBLIC
      properties:
        uid:
          type: string
          description: A unique ID that identifies the modifier only within this order.
          maxLength: 60
          x-release-status: BETA
          nullable: true
        catalog_object_id:
          type: string
          description: >-
            The catalog object ID referencing
            [CatalogModifier](entity:CatalogModifier).
          maxLength: 192
          nullable: true
        catalog_version:
          type: integer
          description: The version of the catalog object that this modifier references.
          format: int64
          nullable: true
        name:
          type: string
          description: The name of the item modifier.
          maxLength: 255
          nullable: true
        quantity:
          type: string
          description: >-
            The quantity of the line item modifier. The modifier quantity can be
            0 or more.

            For example, suppose a restaurant offers a cheeseburger on the menu.
            When a buyer orders

            this item, the restaurant records the purchase by creating an
            `Order` object with a line item

            for a burger. The line item includes a line item modifier: the name
            is cheese and the quantity

            is 1. The buyer has the option to order extra cheese (or no cheese).
            If the buyer chooses

            the extra cheese option, the modifier quantity increases to 2. If
            the buyer does not want

            any cheese, the modifier quantity is set to 0.
          nullable: true
        base_price_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The base price for the modifier.


            `base_price_money` is required for ad hoc modifiers.

            If both `catalog_object_id` and `base_price_money` are set,
            `base_price_money` will

            override the predefined [CatalogModifier](entity:CatalogModifier)
            price.
          nullable: true
        total_price_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The total price of the item modifier for its line item.

            This is the modifier's `base_price_money` multiplied by the line
            item's quantity.
          readOnly: true
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            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).
          x-release-status: BETA
          nullable: true
    OrderLineItemPricingBlocklists:
      type: object
      description: >-
        Describes pricing adjustments that are blocked from automatic

        application to a line item. For more information, see

        [Apply Taxes and
        Discounts](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts).
      x-release-status: BETA
      properties:
        blocked_discounts:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemPricingBlocklistsBlockedDiscount'
          description: >-
            A list of discounts blocked from applying to the line item.

            Discounts can be blocked by the `discount_uid` (for ad hoc
            discounts) or

            the `discount_catalog_object_id` (for catalog discounts).
          nullable: true
        blocked_taxes:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemPricingBlocklistsBlockedTax'
          description: |-
            A list of taxes blocked from applying to the line item.
            Taxes can be blocked by the `tax_uid` (for ad hoc taxes) or
            the `tax_catalog_object_id` (for catalog taxes).
          nullable: true
    OrderLineItemPricingBlocklistsBlockedDiscount:
      type: object
      description: >-
        A discount to block from applying to a line item. The discount must be

        identified by either `discount_uid` or `discount_catalog_object_id`, but
        not both.
      x-release-status: BETA
      properties:
        uid:
          type: string
          description: A unique ID of the `BlockedDiscount` within the order.
          maxLength: 60
          nullable: true
        discount_uid:
          type: string
          description: >-
            The `uid` of the discount that should be blocked. Use this field to
            block

            ad hoc discounts. For catalog discounts, use the
            `discount_catalog_object_id` field.
          maxLength: 60
          nullable: true
        discount_catalog_object_id:
          type: string
          description: >-
            The `catalog_object_id` of the discount that should be blocked.

            Use this field to block catalog discounts. For ad hoc discounts, use
            the

            `discount_uid` field.
          maxLength: 192
          nullable: true
    OrderLineItemPricingBlocklistsBlockedTax:
      type: object
      description: |-
        A tax to block from applying to a line item. The tax must be
        identified by either `tax_uid` or `tax_catalog_object_id`, but not both.
      x-release-status: BETA
      properties:
        uid:
          type: string
          description: A unique ID of the `BlockedTax` within the order.
          maxLength: 60
          nullable: true
        tax_uid:
          type: string
          description: >-
            The `uid` of the tax that should be blocked. Use this field to block

            ad hoc taxes. For catalog, taxes use the `tax_catalog_object_id`
            field.
          maxLength: 60
          nullable: true
        tax_catalog_object_id:
          type: string
          description: |-
            The `catalog_object_id` of the tax that should be blocked.
            Use this field to block catalog taxes. For ad hoc taxes, use the
            `tax_uid` field.
          maxLength: 192
          nullable: true
    OrderLineItemTax:
      type: object
      description: >-
        Represents a tax that applies to one or more line item in the order.


        Fixed-amount, order-scoped taxes are distributed across all non-zero
        line item totals.

        The amount distributed to each line item is relative to the amount the
        item

        contributes to the order subtotal.
      x-release-status: PUBLIC
      properties:
        uid:
          type: string
          description: A unique ID that identifies the tax only within this order.
          maxLength: 60
          x-release-status: BETA
          nullable: true
        catalog_object_id:
          type: string
          description: The catalog object ID referencing [CatalogTax](entity:CatalogTax).
          maxLength: 192
          nullable: true
        catalog_version:
          type: integer
          description: The version of the catalog object that this tax references.
          format: int64
          nullable: true
        name:
          type: string
          description: The tax's name.
          maxLength: 255
          nullable: true
        type:
          $ref: '#/components/schemas/OrderLineItemTaxType'
          description: >-
            Indicates the calculation method used to apply the tax.

            See [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible
            values
          nullable: true
        percentage:
          type: string
          description: >-
            The percentage of the tax, as a string representation of a decimal

            number. For example, a value of `"7.25"` corresponds to a percentage
            of

            7.25%.
          maxLength: 10
          nullable: true
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Application-defined data attached to this tax. 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).
          x-release-status: BETA
          nullable: true
        applied_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The amount of money applied to the order by the tax.

            - For percentage-based taxes, `applied_money` is the money
            calculated using the percentage.
          nullable: true
        scope:
          $ref: '#/components/schemas/OrderLineItemTaxScope'
          description: >-
            Indicates the level at which the tax applies. For `ORDER` scoped
            taxes,

            Square generates references in `applied_taxes` on all order line
            items that do

            not have them. For `LINE_ITEM` scoped taxes, the tax only applies to
            line items

            with references in their `applied_taxes` field.


            This field is immutable. To change the scope, you must delete the
            tax and

            re-add it as a new tax.

            See [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for
            possible values
          nullable: true
        auto_applied:
          type: boolean
          description: >-
            Determines whether the tax was automatically applied to the order
            based on

            the catalog configuration. For an example, see

            [Automatically Apply Taxes to an
            Order](https://developer.squareup.com/docs/orders-api/apply-taxes-and-discounts/auto-apply-taxes).
          readOnly: true
          x-release-status: BETA
    OrderLineItemTaxScope:
      type: string
      enum:
        - OTHER_TAX_SCOPE
        - LINE_ITEM
        - ORDER
      x-enum-elements:
        - name: OTHER_TAX_SCOPE
          description: >-
            Used for reporting only.

            The original transaction tax scope is currently not supported by the
            API.
        - name: LINE_ITEM
          description: |-
            The tax should be applied only to line items specified by
            the `OrderLineItemAppliedTax` reference records.
        - name: ORDER
          description: The tax should be applied to the entire order.
      description: Indicates whether this is a line-item or order-level tax.
      x-release-status: PUBLIC
    OrderLineItemTaxType:
      type: string
      enum:
        - UNKNOWN_TAX
        - ADDITIVE
        - INCLUSIVE
      x-enum-elements:
        - name: UNKNOWN_TAX
          description: >-
            Used for reporting only.

            The original transaction tax type is currently not supported by the
            API.
        - name: ADDITIVE
          description: >-
            The tax is an additive tax. The tax amount is added on top of the
            price.

            For example, an item with a cost of 1.00 USD and a 10% additive tax
            has a total

            cost to the buyer of 1.10 USD.
        - name: INCLUSIVE
          description: >-
            The tax is an inclusive tax. Inclusive taxes are already included

            in the line item price or order total. For example, an item with a
            cost of

            1.00 USD and a 10% inclusive tax has a pretax cost of 0.91 USD

            (91 cents) and a 0.09 (9 cents) tax for a total cost of 1.00 USD to

            the buyer.
      description: Indicates how the tax is applied to the associated line item or order.
      x-release-status: PUBLIC
    OrderMoneyAmounts:
      type: object
      description: A collection of various money amounts.
      x-release-status: BETA
      properties:
        total_money:
          $ref: '#/components/schemas/Money'
          description: The total money.
          nullable: true
        tax_money:
          $ref: '#/components/schemas/Money'
          description: The money associated with taxes.
          nullable: true
        discount_money:
          $ref: '#/components/schemas/Money'
          description: The money associated with discounts.
          nullable: true
        tip_money:
          $ref: '#/components/schemas/Money'
          description: The money associated with tips.
          nullable: true
        service_charge_money:
          $ref: '#/components/schemas/Money'
          description: The money associated with service charges.
          nullable: true
    OrderPricingOptions:
      type: object
      description: >-
        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).
      x-release-status: PUBLIC
      properties:
        auto_apply_discounts:
          type: boolean
          description: |-
            The option to determine whether pricing rule-based
            discounts are automatically applied to an order.
          nullable: true
        auto_apply_taxes:
          type: boolean
          description: >-
            The option to determine whether rule-based taxes are automatically

            applied to an order when the criteria of the corresponding rules are
            met.
          x-release-status: BETA
          nullable: true
    OrderQuantityUnit:
      type: object
      description: >-
        Contains the measurement unit for a quantity and a precision that

        specifies the number of digits after the decimal point for decimal
        quantities.
      x-release-status: PUBLIC
      properties:
        measurement_unit:
          $ref: '#/components/schemas/MeasurementUnit'
          description: |-
            A [MeasurementUnit](entity:MeasurementUnit) that represents the
            unit of measure for the quantity.
          nullable: true
        precision:
          type: integer
          description: >-
            For non-integer quantities, represents the number of digits after
            the decimal point that are

            recorded for this quantity.


            For example, a precision of 1 allows quantities such as `"1.0"` and
            `"1.1"`, but not `"1.01"`.


            Min: 0. Max: 5.
          nullable: true
        catalog_object_id:
          type: string
          description: |-
            The catalog object ID referencing the
            [CatalogMeasurementUnit](entity:CatalogMeasurementUnit).

            This field is set when this is a catalog-backed measurement unit.
          nullable: true
        catalog_version:
          type: integer
          description: >-
            The version of the catalog object that this measurement unit
            references.


            This field is set when this is a catalog-backed measurement unit.
          format: int64
          nullable: true
    OrderReturn:
      type: object
      description: >-
        The set of line items, service charges, taxes, discounts, tips, and
        other items being returned in an order.
      x-release-status: BETA
      properties:
        uid:
          type: string
          description: A unique ID that identifies the return only within this order.
          maxLength: 60
          nullable: true
        source_order_id:
          type: string
          description: >-
            An order that contains the original sale of these return line items.
            This is unset

            for unlinked returns.
          nullable: true
        return_line_items:
          type: array
          items:
            $ref: '#/components/schemas/OrderReturnLineItem'
          description: A collection of line items that are being returned.
          nullable: true
        return_service_charges:
          type: array
          items:
            $ref: '#/components/schemas/OrderReturnServiceCharge'
          description: A collection of service charges that are being returned.
          nullable: true
        return_taxes:
          type: array
          items:
            $ref: '#/components/schemas/OrderReturnTax'
          description: >-
            A collection of references to taxes being returned for an order,
            including the total

            applied tax amount to be returned. The taxes must reference a
            top-level tax ID from the source

            order.
          readOnly: true
        return_discounts:
          type: array
          items:
            $ref: '#/components/schemas/OrderReturnDiscount'
          description: >-
            A collection of references to discounts being returned for an order,
            including the total

            applied discount amount to be returned. The discounts must reference
            a top-level discount ID

            from the source order.
          readOnly: true
        return_tips:
          type: array
          items:
            $ref: '#/components/schemas/OrderReturnTip'
          description: A collection of references to tips being returned for an order.
          nullable: true
        rounding_adjustment:
          $ref: '#/components/schemas/OrderRoundingAdjustment'
          description: >-
            A positive or negative rounding adjustment to the total value being
            returned. Adjustments are commonly

            used to apply cash rounding when the minimum unit of the account is
            smaller than the lowest

            physical denomination of the currency.
          nullable: true
        return_amounts:
          $ref: '#/components/schemas/OrderMoneyAmounts'
          description: An aggregate monetary value being returned by this return entry.
          nullable: true
    OrderReturnDiscount:
      type: object
      description: >-
        Represents a discount being returned that applies to one or more return
        line items in an

        order.


        Fixed-amount, order-scoped discounts are distributed across all non-zero
        return line item totals.

        The amount distributed to each return line item is relative to that
        items contribution to the

        order subtotal.
      x-release-status: BETA
      properties:
        uid:
          type: string
          description: >-
            A unique ID that identifies the returned discount only within this
            order.
          maxLength: 60
          nullable: true
        source_discount_uid:
          type: string
          description: >-
            The discount `uid` from the order that contains the original
            application of this discount.
          maxLength: 60
          nullable: true
        catalog_object_id:
          type: string
          description: >-
            The catalog object ID referencing
            [CatalogDiscount](entity:CatalogDiscount).
          maxLength: 192
          nullable: true
        catalog_version:
          type: integer
          description: The version of the catalog object that this discount references.
          format: int64
          nullable: true
        name:
          type: string
          description: The discount's name.
          maxLength: 255
          nullable: true
        type:
          $ref: '#/components/schemas/OrderLineItemDiscountType'
          description: >-
            The type of the discount. If it is created by the API, it is
            `FIXED_PERCENTAGE` or `FIXED_AMOUNT`.


            Discounts that do not reference a catalog object ID must have a type
            of

            `FIXED_PERCENTAGE` or `FIXED_AMOUNT`.

            See [OrderLineItemDiscountType](#type-orderlineitemdiscounttype) for
            possible values
          nullable: true
        percentage:
          type: string
          description: >-
            The percentage of the tax, as a string representation of a decimal
            number.

            A value of `"7.25"` corresponds to a percentage of 7.25%.


            `percentage` is not set for amount-based discounts.
          maxLength: 10
          nullable: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The total declared monetary amount of the discount.

            `amount_money` is not set for percentage-based discounts.
          nullable: true
        applied_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of discount actually applied to this line item. When an
            amount-based

            discount is at the order level, this value is different from
            `amount_money` because the discount

            is distributed across the line items.
          readOnly: true
        scope:
          $ref: '#/components/schemas/OrderLineItemDiscountScope'
          description: >-
            Indicates the level at which the `OrderReturnDiscount` applies. For
            `ORDER` scoped

            discounts, the server generates references in `applied_discounts` on
            all

            `OrderReturnLineItem`s. For `LINE_ITEM` scoped discounts, the
            discount is only applied to

            `OrderReturnLineItem`s with references in their `applied_discounts`
            field.

            See [OrderLineItemDiscountScope](#type-orderlineitemdiscountscope)
            for possible values
          nullable: true
    OrderReturnLineItem:
      type: object
      description: The line item being returned in an order.
      x-release-status: BETA
      required:
        - quantity
      properties:
        uid:
          type: string
          description: A unique ID for this return line-item entry.
          maxLength: 60
          nullable: true
        source_line_item_uid:
          type: string
          description: The `uid` of the line item in the original sale order.
          maxLength: 60
          nullable: true
        name:
          type: string
          description: The name of the line item.
          maxLength: 512
          nullable: true
        quantity:
          type: string
          description: |-
            The quantity returned, formatted as a decimal number.
            For example, `"3"`.

            Line items with a `quantity_unit` can have non-integer quantities.
            For example, `"1.70000"`.
          minLength: 1
          maxLength: 12
        quantity_unit:
          $ref: '#/components/schemas/OrderQuantityUnit'
          description: >-
            The unit and precision that this return line item's quantity is
            measured in.
          nullable: true
        note:
          type: string
          description: The note of the return line item.
          maxLength: 2000
          nullable: true
        catalog_object_id:
          type: string
          description: >-
            The [CatalogItemVariation](entity:CatalogItemVariation) ID applied
            to this return line item.
          maxLength: 192
          nullable: true
        catalog_version:
          type: integer
          description: The version of the catalog object that this line item references.
          format: int64
          nullable: true
        variation_name:
          type: string
          description: The name of the variation applied to this return line item.
          maxLength: 400
          nullable: true
        item_type:
          $ref: '#/components/schemas/OrderLineItemItemType'
          description: >-
            The type of line item: an itemized return, a non-itemized return
            (custom amount),

            or the return of an unactivated gift card sale.

            See [OrderLineItemItemType](#type-orderlineitemitemtype) for
            possible values
          nullable: true
        return_modifiers:
          type: array
          items:
            $ref: '#/components/schemas/OrderReturnLineItemModifier'
          description: >-
            The [CatalogModifier](entity:CatalogModifier)s applied to this line
            item.
          nullable: true
        applied_taxes:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemAppliedTax'
          description: >-
            The list of references to `OrderReturnTax` entities applied to the
            return line item. Each

            `OrderLineItemAppliedTax` has a `tax_uid` that references the `uid`
            of a top-level

            `OrderReturnTax` applied to the return line item. On reads, the
            applied amount

            is populated.
          nullable: true
        applied_discounts:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemAppliedDiscount'
          description: >-
            The list of references to `OrderReturnDiscount` entities applied to
            the return line item. Each

            `OrderLineItemAppliedDiscount` has a `discount_uid` that references
            the `uid` of a top-level

            `OrderReturnDiscount` applied to the return line item. On reads, the
            applied amount

            is populated.
          nullable: true
        base_price_money:
          $ref: '#/components/schemas/Money'
          description: The base price for a single unit of the line item.
          nullable: true
        variation_total_price_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The total price of all item variations returned in this line item.

            The price is calculated as `base_price_money` multiplied by
            `quantity` and

            does not include modifiers.
          readOnly: true
        gross_return_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The gross return amount of money calculated as (item base price +
            modifiers price) * quantity.
          readOnly: true
        total_tax_money:
          $ref: '#/components/schemas/Money'
          description: The total amount of tax money to return for the line item.
          readOnly: true
        total_discount_money:
          $ref: '#/components/schemas/Money'
          description: The total amount of discount money to return for the line item.
          readOnly: true
        total_money:
          $ref: '#/components/schemas/Money'
          description: The total amount of money to return for this line item.
          readOnly: true
        applied_service_charges:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemAppliedServiceCharge'
          description: >-
            The list of references to `OrderReturnServiceCharge` entities
            applied to the return

            line item. Each `OrderLineItemAppliedServiceCharge` has a
            `service_charge_uid` that

            references the `uid` of a top-level `OrderReturnServiceCharge`
            applied to the return line

            item. On reads, the applied amount is populated.
          nullable: true
        total_service_charge_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The total amount of apportioned service charge money to return for
            the line item.
          readOnly: true
    OrderReturnLineItemModifier:
      type: object
      description: A line item modifier being returned.
      x-release-status: BETA
      properties:
        uid:
          type: string
          description: >-
            A unique ID that identifies the return modifier only within this
            order.
          maxLength: 60
          nullable: true
        source_modifier_uid:
          type: string
          description: |-
            The modifier `uid` from the order's line item that contains the
            original sale of this line item modifier.
          maxLength: 60
          nullable: true
        catalog_object_id:
          type: string
          description: >-
            The catalog object ID referencing
            [CatalogModifier](entity:CatalogModifier).
          maxLength: 192
          nullable: true
        catalog_version:
          type: integer
          description: >-
            The version of the catalog object that this line item modifier
            references.
          format: int64
          nullable: true
        name:
          type: string
          description: The name of the item modifier.
          maxLength: 255
          nullable: true
        base_price_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The base price for the modifier.


            `base_price_money` is required for ad hoc modifiers.

            If both `catalog_object_id` and `base_price_money` are set,
            `base_price_money` overrides the predefined
            [CatalogModifier](entity:CatalogModifier) price.
          nullable: true
        total_price_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The total price of the item modifier for its line item.

            This is the modifier's `base_price_money` multiplied by the line
            item's quantity.
          readOnly: true
        quantity:
          type: string
          description: >-
            The quantity of the line item modifier. The modifier quantity can be
            0 or more.

            For example, suppose a restaurant offers a cheeseburger on the menu.
            When a buyer orders

            this item, the restaurant records the purchase by creating an
            `Order` object with a line item

            for a burger. The line item includes a line item modifier: the name
            is cheese and the quantity

            is 1. The buyer has the option to order extra cheese (or no cheese).
            If the buyer chooses

            the extra cheese option, the modifier quantity increases to 2. If
            the buyer does not want

            any cheese, the modifier quantity is set to 0.
          nullable: true
    OrderReturnServiceCharge:
      type: object
      description: Represents the service charge applied to the original order.
      x-release-status: PUBLIC
      properties:
        uid:
          type: string
          description: >-
            A unique ID that identifies the return service charge only within
            this order.
          maxLength: 60
          x-release-status: BETA
          nullable: true
        source_service_charge_uid:
          type: string
          description: |-
            The service charge `uid` from the order containing the original
            service charge. `source_service_charge_uid` is `null` for
            unlinked returns.
          maxLength: 60
          nullable: true
        name:
          type: string
          description: The name of the service charge.
          maxLength: 255
          nullable: true
        catalog_object_id:
          type: string
          description: >-
            The catalog object ID of the associated
            [OrderServiceCharge](entity:OrderServiceCharge).
          maxLength: 192
          nullable: true
        catalog_version:
          type: integer
          description: >-
            The version of the catalog object that this service charge
            references.
          format: int64
          nullable: true
        percentage:
          type: string
          description: |-
            The percentage of the service charge, as a string representation of
            a decimal number. For example, a value of `"7.25"` corresponds to a
            percentage of 7.25%.

            Either `percentage` or `amount_money` should be set, but not both.
          maxLength: 10
          nullable: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The amount of a non-percentage-based service charge.

            Either `percentage` or `amount_money` should be set, but not both.
          nullable: true
        applied_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money applied to the order by the service charge,
            including

            any inclusive tax amounts, as calculated by Square.


            - For fixed-amount service charges, `applied_money` is equal to
            `amount_money`.

            - For percentage-based service charges, `applied_money` is the money
            calculated using the percentage.
          readOnly: true
        total_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The total amount of money to collect for the service charge.


            __NOTE__: If an inclusive tax is applied to the service charge,
            `total_money`

            does not equal `applied_money` plus `total_tax_money` because the
            inclusive

            tax amount is already included in both `applied_money` and
            `total_tax_money`.
          readOnly: true
        total_tax_money:
          $ref: '#/components/schemas/Money'
          description: The total amount of tax money to collect for the service charge.
          readOnly: true
        calculation_phase:
          $ref: '#/components/schemas/OrderServiceChargeCalculationPhase'
          description: >-
            The calculation phase after which to apply the service charge.

            See
            [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase)
            for possible values
          readOnly: true
        taxable:
          type: boolean
          description: |-
            Indicates whether the surcharge can be taxed. Service charges
            calculated in the `TOTAL_PHASE` cannot be marked as taxable.
          nullable: true
        applied_taxes:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemAppliedTax'
          description: >-
            The list of references to `OrderReturnTax` entities applied to the

            `OrderReturnServiceCharge`. Each `OrderLineItemAppliedTax` has a
            `tax_uid`

            that references the `uid` of a top-level `OrderReturnTax` that is
            being

            applied to the `OrderReturnServiceCharge`. On reads, the applied
            amount is

            populated.
          x-release-status: BETA
          nullable: true
        treatment_type:
          $ref: '#/components/schemas/OrderServiceChargeTreatmentType'
          description: >-
            The treatment type of the service charge.

            See
            [OrderServiceChargeTreatmentType](#type-orderservicechargetreatmenttype)
            for possible values
          x-release-status: BETA
          nullable: true
        scope:
          $ref: '#/components/schemas/OrderServiceChargeScope'
          description: >-
            Indicates the level at which the apportioned service charge applies.
            For `ORDER`

            scoped service charges, Square generates references in
            `applied_service_charges` on

            all order line items that do not have them. For `LINE_ITEM` scoped
            service charges,

            the service charge only applies to line items with a service charge
            reference in their

            `applied_service_charges` field.


            This field is immutable. To change the scope of an apportioned
            service charge, you must delete

            the apportioned service charge and re-add it as a new apportioned
            service charge.

            See [OrderServiceChargeScope](#type-orderservicechargescope) for
            possible values
          x-release-status: BETA
          nullable: true
    OrderReturnTax:
      type: object
      description: >-
        Represents a tax being returned that applies to one or more return line
        items in an order.


        Fixed-amount, order-scoped taxes are distributed across all non-zero
        return line item totals.

        The amount distributed to each return line item is relative to that
        items contribution to the

        order subtotal.
      x-release-status: BETA
      properties:
        uid:
          type: string
          description: A unique ID that identifies the returned tax only within this order.
          maxLength: 60
          nullable: true
        source_tax_uid:
          type: string
          description: The tax `uid` from the order that contains the original tax charge.
          maxLength: 60
          nullable: true
        catalog_object_id:
          type: string
          description: The catalog object ID referencing [CatalogTax](entity:CatalogTax).
          maxLength: 192
          nullable: true
        catalog_version:
          type: integer
          description: The version of the catalog object that this tax references.
          format: int64
          nullable: true
        name:
          type: string
          description: The tax's name.
          maxLength: 255
          nullable: true
        type:
          $ref: '#/components/schemas/OrderLineItemTaxType'
          description: >-
            Indicates the calculation method used to apply the tax.

            See [OrderLineItemTaxType](#type-orderlineitemtaxtype) for possible
            values
          nullable: true
        percentage:
          type: string
          description: >-
            The percentage of the tax, as a string representation of a decimal
            number.

            For example, a value of `"7.25"` corresponds to a percentage of
            7.25%.
          maxLength: 10
          nullable: true
        applied_money:
          $ref: '#/components/schemas/Money'
          description: The amount of money applied by the tax in an order.
          readOnly: true
        scope:
          $ref: '#/components/schemas/OrderLineItemTaxScope'
          description: >-
            Indicates the level at which the `OrderReturnTax` applies. For
            `ORDER` scoped

            taxes, Square generates references in `applied_taxes` on all

            `OrderReturnLineItem`s. For `LINE_ITEM` scoped taxes, the tax is
            only applied to

            `OrderReturnLineItem`s with references in their `applied_discounts`
            field.

            See [OrderLineItemTaxScope](#type-orderlineitemtaxscope) for
            possible values
          nullable: true
    OrderReturnTip:
      type: object
      description: A tip being returned.
      x-release-status: BETA
      properties:
        uid:
          type: string
          description: A unique ID that identifies the tip only within this order.
          maxLength: 60
          nullable: true
        applied_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The amount of tip being returned
            --
          readOnly: true
        source_tender_uid:
          type: string
          description: >-
            The tender `uid` from the order that contains the original
            application of this tip.
          maxLength: 192
          nullable: true
        source_tender_id:
          type: string
          description: >-
            The tender `id` from the order that contains the original
            application of this tip.
          maxLength: 192
          nullable: true
    OrderReward:
      type: object
      description: >-
        Represents a reward that can be applied to an order if the necessary

        reward tier criteria are met. Rewards are created through the Loyalty
        API.
      x-release-status: BETA
      required:
        - id
        - reward_tier_id
      properties:
        id:
          type: string
          description: The identifier of the reward.
          minLength: 1
        reward_tier_id:
          type: string
          description: The identifier of the reward tier corresponding to this reward.
          minLength: 1
    OrderRoundingAdjustment:
      type: object
      description: >-
        A rounding adjustment of the money being returned. Commonly used to
        apply cash rounding

        when the minimum unit of the account is smaller than the lowest physical
        denomination of the currency.
      x-release-status: BETA
      properties:
        uid:
          type: string
          description: >-
            A unique ID that identifies the rounding adjustment only within this
            order.
          maxLength: 60
          nullable: true
        name:
          type: string
          description: The name of the rounding adjustment from the original sale order.
          nullable: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: The actual rounding adjustment amount.
          nullable: true
    OrderServiceCharge:
      type: object
      description: Represents a service charge applied to an order.
      x-release-status: PUBLIC
      properties:
        uid:
          type: string
          description: >-
            A unique ID that identifies the service charge only within this
            order.
          maxLength: 60
          x-release-status: BETA
          nullable: true
        name:
          type: string
          description: The name of the service charge.
          maxLength: 512
          nullable: true
        catalog_object_id:
          type: string
          description: >-
            The catalog object ID referencing the service charge
            [CatalogObject](entity:CatalogObject).
          maxLength: 192
          nullable: true
        catalog_version:
          type: integer
          description: >-
            The version of the catalog object that this service charge
            references.
          format: int64
          nullable: true
        percentage:
          type: string
          description: >-
            The service charge percentage as a string representation of a

            decimal number. For example, `"7.25"` indicates a service charge of
            7.25%.


            Exactly 1 of `percentage` or `amount_money` should be set.
          maxLength: 10
          nullable: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The amount of a non-percentage-based service charge.

            Exactly one of `percentage` or `amount_money` should be set.
          nullable: true
        applied_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money applied to the order by the service charge,

            including any inclusive tax amounts, as calculated by Square.


            - For fixed-amount service charges, `applied_money` is equal to
            `amount_money`.

            - For percentage-based service charges, `applied_money` is the money

            calculated using the percentage.
          readOnly: true
        total_money:
          $ref: '#/components/schemas/Money'
          description: |-
            The total amount of money to collect for the service charge.

            __Note__: If an inclusive tax is applied to the service charge,
            `total_money` does not equal `applied_money` plus `total_tax_money`
            because the inclusive tax amount is already included in both
            `applied_money` and `total_tax_money`.
          readOnly: true
        total_tax_money:
          $ref: '#/components/schemas/Money'
          description: The total amount of tax money to collect for the service charge.
          readOnly: true
        calculation_phase:
          $ref: '#/components/schemas/OrderServiceChargeCalculationPhase'
          description: >-
            The calculation phase at which to apply the service charge.

            See
            [OrderServiceChargeCalculationPhase](#type-orderservicechargecalculationphase)
            for possible values
          nullable: true
        taxable:
          type: boolean
          description: >-
            Indicates whether the service charge can be taxed. If set to `true`,

            order-level taxes automatically apply to the service charge. Note
            that

            service charges calculated in the `TOTAL_PHASE` cannot be marked as
            taxable.
          nullable: true
        applied_taxes:
          type: array
          items:
            $ref: '#/components/schemas/OrderLineItemAppliedTax'
          description: >-
            The list of references to the taxes applied to this service charge.
            Each

            `OrderLineItemAppliedTax` has a `tax_uid` that references the `uid`
            of a top-level

            `OrderLineItemTax` that is being applied to this service charge. On
            reads, the amount applied

            is populated.


            An `OrderLineItemAppliedTax` is automatically created on every
            taxable service charge

            for all `ORDER` scoped taxes that are added to the order.
            `OrderLineItemAppliedTax` records

            for `LINE_ITEM` scoped taxes must be added in requests for the tax
            to apply to any taxable

            service charge. Taxable service charges have the `taxable` field set
            to `true` and calculated

            in the `SUBTOTAL_PHASE`.


            To change the amount of a tax, modify the referenced top-level tax.
          x-release-status: BETA
          nullable: true
        metadata:
          type: object
          additionalProperties:
            type: string
          description: >-
            Application-defined data attached to this service charge. 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).
          x-release-status: BETA
          nullable: true
        type:
          $ref: '#/components/schemas/OrderServiceChargeType'
          description: >-
            The type of the service charge.

            See [OrderServiceChargeType](#type-orderservicechargetype) for
            possible values
          readOnly: true
        treatment_type:
          $ref: '#/components/schemas/OrderServiceChargeTreatmentType'
          description: >-
            The treatment type of the service charge.

            See
            [OrderServiceChargeTreatmentType](#type-orderservicechargetreatmenttype)
            for possible values
          x-release-status: BETA
          nullable: true
        scope:
          $ref: '#/components/schemas/OrderServiceChargeScope'
          description: >-
            Indicates the level at which the apportioned service charge applies.
            For `ORDER`

            scoped service charges, Square generates references in
            `applied_service_charges` on

            all order line items that do not have them. For `LINE_ITEM` scoped
            service charges,

            the service charge only applies to line items with a service charge
            reference in their

            `applied_service_charges` field.


            This field is immutable. To change the scope of an apportioned
            service charge, you must delete

            the apportioned service charge and re-add it as a new apportioned
            service charge.

            See [OrderServiceChargeScope](#type-orderservicechargescope) for
            possible values
          x-release-status: BETA
          nullable: true
    OrderServiceChargeCalculationPhase:
      type: string
      enum:
        - SUBTOTAL_PHASE
        - TOTAL_PHASE
        - APPORTIONED_PERCENTAGE_PHASE
        - APPORTIONED_AMOUNT_PHASE
      x-enum-elements:
        - name: SUBTOTAL_PHASE
          description: |-
            The service charge is applied after discounts, but before
            taxes.
        - name: TOTAL_PHASE
          description: |-
            The service charge is applied after all discounts and taxes
            are applied.
        - name: APPORTIONED_PERCENTAGE_PHASE
          description: >-
            The service charge is calculated as a compounding adjustment

            after any discounts, but before amount based apportioned service
            charges

            and any tax considerations.
        - name: APPORTIONED_AMOUNT_PHASE
          description: >-
            The service charge is calculated as a compounding adjustment

            after any discounts and percentage based apportioned service
            charges,

            but before any tax considerations.
      description: >-
        Represents a phase in the process of calculating order totals.

        Service charges are applied after the indicated phase.


        [Read more about how order totals are
        calculated.](https://developer.squareup.com/docs/orders-api/how-it-works#how-totals-are-calculated)
      x-release-status: PUBLIC
    OrderServiceChargeScope:
      type: string
      enum:
        - OTHER_SERVICE_CHARGE_SCOPE
        - LINE_ITEM
        - ORDER
      x-enum-elements:
        - name: OTHER_SERVICE_CHARGE_SCOPE
          description: >-
            Used for reporting only.

            The original transaction service charge scope is currently not
            supported by the API.
        - name: LINE_ITEM
          description: |-
            The service charge should be applied to only line items specified by
            `OrderLineItemAppliedServiceCharge` reference records.
        - name: ORDER
          description: The service charge should be applied to the entire order.
      description: |-
        Indicates whether this is a line-item or order-level apportioned
        service charge.
      x-release-status: BETA
    OrderServiceChargeTreatmentType:
      type: string
      enum:
        - LINE_ITEM_TREATMENT
        - APPORTIONED_TREATMENT
      x-enum-elements:
        - name: LINE_ITEM_TREATMENT
          description: ''
        - name: APPORTIONED_TREATMENT
          description: ''
      description: >-
        Indicates whether the service charge will be treated as a value-holding
        line item or

        apportioned toward a line item.
      x-release-status: BETA
    OrderServiceChargeType:
      type: string
      enum:
        - AUTO_GRATUITY
        - CUSTOM
      x-enum-elements:
        - name: AUTO_GRATUITY
          description: ''
        - name: CUSTOM
          description: ''
      x-release-status: PUBLIC
    OrderSource:
      type: object
      description: Represents the origination details of an order.
      x-release-status: PUBLIC
      properties:
        name:
          type: string
          description: >-
            The name used to identify the place (physical or digital) that an
            order originates.

            If unset, the name defaults to the name of the application that
            created the order.
          nullable: true
    OrderState:
      type: string
      enum:
        - OPEN
        - COMPLETED
        - CANCELED
        - DRAFT
      x-enum-elements:
        - name: OPEN
          description: Indicates that the order is open. Open orders can be updated.
        - name: COMPLETED
          description: >-
            Indicates that the order is completed. Completed orders are fully
            paid. This is a terminal state.
        - name: CANCELED
          description: >-
            Indicates that the order is canceled. Canceled orders are not paid.
            This is a terminal state.
        - name: DRAFT
          description: >-
            Indicates that the order is in a draft state. Draft orders can be
            updated,

            but cannot be paid or fulfilled.

            For more information, see [Create
            Orders](https://developer.squareup.com/docs/orders-api/create-orders).
      description: The state of the order.
      x-release-status: PUBLIC
    OrderUpdated:
      type: object
      x-release-status: BETA
      properties:
        order_id:
          type: string
          description: The order's unique ID.
          nullable: true
        version:
          type: integer
          description: >-
            The version number, which is incremented each time an update is
            committed to the order.

            Orders that were 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)
        location_id:
          type: string
          description: The ID of the seller location that this order is associated with.
          nullable: true
        state:
          $ref: '#/components/schemas/OrderState'
          description: |-
            The state of the order.
            See [OrderState](#type-orderstate) for possible values
          nullable: true
        created_at:
          type: string
          description: The timestamp for when the order was created, in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp for when the order was last updated, in RFC 3339
            format.
          readOnly: true
    OrderUpdatedObject:
      type: object
      x-release-status: BETA
      properties:
        order_updated:
          $ref: '#/components/schemas/OrderUpdated'
          description: Information about the updated order.
          nullable: true
    PaginationCursor:
      type: object
      description: >-
        Used *internally* to encapsulate pagination details. The resulting proto
        will be base62 encoded

        in order to produce a cursor that can be used externally.
      x-release-status: BETA
      properties:
        order_value:
          type: string
          description: >-
            The ID of the last resource in the current page. The page can be in
            an ascending or

            descending order
          nullable: true
    PauseSubscriptionRequest:
      type: object
      description: >-
        Defines input parameters in a request to the

        [PauseSubscription](api-endpoint:Subscriptions-PauseSubscription)
        endpoint.
      x-release-status: BETA
      properties:
        pause_effective_date:
          type: string
          description: >-
            The `YYYY-MM-DD`-formatted date when the scheduled `PAUSE` action
            takes place on the subscription.


            When this date is unspecified or falls within the current billing
            cycle, the subscription is paused

            on the starting date of the next billing cycle.
          nullable: true
        pause_cycle_duration:
          type: integer
          description: >-
            The number of billing cycles the subscription will be paused before
            it is reactivated. 


            When this is set, a `RESUME` action is also scheduled to take place
            on the subscription at 

            the end of the specified pause cycle duration. In this case, neither
            `resume_effective_date` 

            nor `resume_change_timing` may be specified.
          format: int64
          nullable: true
        resume_effective_date:
          type: string
          description: >-
            The date when the subscription is reactivated by a scheduled
            `RESUME` action. 

            This date must be at least one billing cycle ahead of
            `pause_effective_date`.
          nullable: true
        resume_change_timing:
          $ref: '#/components/schemas/ChangeTiming'
          description: >-
            The timing whether the subscription is reactivated immediately or at
            the end of the billing cycle, relative to 

            `resume_effective_date`.

            See [ChangeTiming](#type-changetiming) for possible values
          nullable: true
        pause_reason:
          type: string
          description: The user-provided reason to pause the subscription.
          maxLength: 255
          nullable: true
    PauseSubscriptionResponse:
      type: object
      description: >-
        Defines output parameters in a response from the

        [PauseSubscription](api-endpoint:Subscriptions-PauseSubscription)
        endpoint.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered during the request.
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: The subscription to be paused by the scheduled `PAUSE` action.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionAction'
          description: >-
            The list of a `PAUSE` action and a possible `RESUME` action created
            by the request.
      example:
        actions:
          - effective_date: '2023-11-17'
            id: 99b2439e-63f7-3ad5-95f7-ab2447a80673
            type: PAUSE
        subscription:
          card_id: ccof:qy5x8hHGYsgLrp4Q4GB
          created_at: '2023-06-20T21:53:10Z'
          customer_id: CHFGVKYY8RSV93M5KCYTG4PN0G
          id: 56214fb2-cc85-47a1-93bc-44f3766bb56f
          location_id: S8GWD5R9QB376
          phases:
            - order_template_id: U2NaowWxzXwpsZU697x7ZHOAnCNZY
              ordinal: 0
              plan_phase_uid: X2Q2AONPB3RB64Y27S25QCZP
              uid: 873451e0-745b-4e87-ab0b-c574933fe616
          plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
          source:
            name: My Application
          start_date: '2023-06-20'
          status: ACTIVE
          timezone: America/Los_Angeles
          version: 1
    PayOrderRequest:
      type: object
      description: |-
        Defines the fields that are included in requests to the
        [PayOrder](api-endpoint:Orders-PayOrder) endpoint.
      x-release-status: BETA
      required:
        - idempotency_key
      properties:
        idempotency_key:
          type: string
          description: >-
            A value you specify that uniquely identifies this request among
            requests you have sent. If

            you are unsure whether a particular payment request was completed
            successfully, you can reattempt

            it with the same idempotency key without worrying about duplicate
            payments.


            For more information, see
            [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).
          minLength: 1
          maxLength: 192
        order_version:
          type: integer
          description: >-
            The version of the order being paid. If not supplied, the latest
            version will be paid.
          nullable: true
        payment_ids:
          type: array
          items:
            type: string
          description: |-
            The IDs of the [payments](entity:Payment) to collect.
            The payment total must match the order total.
          nullable: true
      example:
        idempotency_key: c043a359-7ad9-4136-82a9-c3f1d66dcbff
        payment_ids:
          - EnZdNAlWCmfh6Mt5FMNST1o7taB
          - 0LRiVlbXVwe8ozu4KbZxd12mvaB
    PayOrderResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of a request
        to the

        [PayOrder](api-endpoint:Orders-PayOrder) endpoint.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        order:
          $ref: '#/components/schemas/Order'
          description: The paid, updated [order](entity:Order).
      example:
        order:
          closed_at: '2019-08-06T02:47:37.140Z'
          created_at: '2019-08-06T02:47:35.693Z'
          id: lgwOlEityYPJtcuvKTVKT1pA986YY
          line_items:
            - base_price_money:
                amount: 500
                currency: USD
              gross_sales_money:
                amount: 500
                currency: USD
              name: Item 1
              quantity: '1'
              total_discount_money:
                amount: 0
                currency: USD
              total_money:
                amount: 500
                currency: USD
              total_service_charge_money:
                amount: 0
                currency: USD
              total_tax_money:
                amount: 0
                currency: USD
              uid: QW6kofLHJK7JEKMjlSVP5C
            - base_price_money:
                amount: 750
                currency: USD
              gross_sales_money:
                amount: 1500
                currency: USD
              name: Item 2
              quantity: '2'
              total_discount_money:
                amount: 0
                currency: USD
              total_money:
                amount: 1500
                currency: USD
              total_service_charge_money:
                amount: 0
                currency: USD
              total_tax_money:
                amount: 0
                currency: USD
              uid: zhw8MNfRGdFQMI2WE1UBJD
          location_id: P3CCK6HSNDAS7
          net_amounts:
            discount_money:
              amount: 0
              currency: USD
            service_charge_money:
              amount: 0
              currency: USD
            tax_money:
              amount: 0
              currency: USD
            tip_money:
              amount: 0
              currency: USD
            total_money:
              amount: 2000
              currency: USD
          source:
            name: Source Name
          state: COMPLETED
          tenders:
            - amount_money:
                amount: 1000
                currency: USD
              card_details:
                card:
                  card_brand: VISA
                  exp_month: 2
                  exp_year: 2022
                  fingerprint: >-
                    sq-1-n_BL15KP87ClDa4-h2nXOI0fp5VnxNH6hfhzqhptTfAgxgLuGFcg6jIPngDz4IkkTQ
                  last_4: '1111'
                entry_method: KEYED
                status: CAPTURED
              created_at: '2019-08-06T02:47:36.293Z'
              id: EnZdNAlWCmfh6Mt5FMNST1o7taB
              location_id: P3CCK6HSNDAS7
              payment_id: EnZdNAlWCmfh6Mt5FMNST1o7taB
              transaction_id: lgwOlEityYPJtcuvKTVKT1pA986YY
              type: CARD
            - amount_money:
                amount: 1000
                currency: USD
              card_details:
                card:
                  card_brand: VISA
                  exp_month: 2
                  exp_year: 2022
                  fingerprint: >-
                    sq-1-n_BL15KP87ClDa4-h2nXOI0fp5VnxNH6hfhzqhptTfAgxgLuGFcg6jIPngDz4IkkTQ
                  last_4: '1111'
                entry_method: KEYED
                status: CAPTURED
              created_at: '2019-08-06T02:47:36.809Z'
              id: 0LRiVlbXVwe8ozu4KbZxd12mvaB
              location_id: P3CCK6HSNDAS7
              payment_id: 0LRiVlbXVwe8ozu4KbZxd12mvaB
              transaction_id: lgwOlEityYPJtcuvKTVKT1pA986YY
              type: CARD
          total_discount_money:
            amount: 0
            currency: USD
          total_money:
            amount: 2000
            currency: USD
          total_service_charge_money:
            amount: 0
            currency: USD
          total_tax_money:
            amount: 0
            currency: USD
          updated_at: '2019-08-06T02:47:37.140Z'
          version: 4
    Payment:
      type: object
      description: Represents a payment processed by the Square API.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: A unique ID for the payment.
          maxLength: 192
          readOnly: true
        created_at:
          type: string
          description: The timestamp of when the payment was created, in RFC 3339 format.
          maxLength: 32
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp of when the payment was last updated, in RFC 3339
            format.
          maxLength: 32
          readOnly: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount processed for this payment, not including `tip_money`.


            The amount is specified in the smallest denomination of the
            applicable currency (for example,

            US dollar amounts are specified in cents). For more information, see

            [Working with Monetary
            Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).
          nullable: true
        tip_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount designated as a tip. 


            This amount is specified in the smallest denomination of the
            applicable currency (for example,

            US dollar amounts are specified in cents). For more information, see

            [Working with Monetary
            Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).
          nullable: true
        total_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The total amount for the payment, including `amount_money` and
            `tip_money`.

            This amount is specified in the smallest denomination of the
            applicable currency (for example,

            US dollar amounts are specified in cents). For more information, see

            [Working with Monetary
            Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).
          readOnly: true
        app_fee_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount the developer is taking as a fee for facilitating the
            payment on behalf

            of the seller. This amount is specified in the smallest denomination
            of the applicable currency

            (for example, US dollar amounts are specified in cents). For more
            information,

            see [Take Payments and Collect
            Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).


            The amount cannot be more than 90% of the `total_money` value.


            To set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth
            permission is required.

            For more information, see
            [Permissions](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees#permissions).
          nullable: true
        approved_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money approved for this payment. This value may change
            if Square chooses to

            obtain reauthorization as part of a call to
            [UpdatePayment](api-endpoint:Payments-UpdatePayment).
          nullable: true
        processing_fee:
          type: array
          items:
            $ref: '#/components/schemas/ProcessingFee'
          description: >-
            The processing fees and fee adjustments assessed by Square for this
            payment.
          readOnly: true
        refunded_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The total amount of the payment refunded to date. 


            This amount is specified in the smallest denomination of the
            applicable currency (for example,

            US dollar amounts are specified in cents).
          readOnly: true
        status:
          type: string
          description: >-
            Indicates whether the payment is APPROVED, PENDING, COMPLETED,
            CANCELED, or FAILED.
          maxLength: 50
          readOnly: true
        delay_duration:
          type: string
          description: >-
            The duration of time after the payment's creation when Square
            automatically applies the

            `delay_action` to the payment. This automatic `delay_action` applies
            only to payments that

            do not reach a terminal state (COMPLETED, CANCELED, or FAILED)
            before the `delay_duration`

            time period.


            This field is specified as a time duration, in RFC 3339 format.


            Notes:

            This feature is only supported for card payments.


            Default:


            - Card-present payments: "PT36H" (36 hours) from the creation time.

            - Card-not-present payments: "P7D" (7 days) from the creation time.
          readOnly: true
        delay_action:
          type: string
          description: >-
            The action to be applied to the payment when the `delay_duration`
            has elapsed.


            Current values include `CANCEL` and `COMPLETE`.
          nullable: true
        delayed_until:
          type: string
          description: >-
            The read-only timestamp of when the `delay_action` is automatically
            applied,

            in RFC 3339 format.


            Note that this field is calculated by summing the payment's
            `delay_duration` and `created_at`

            fields. The `created_at` field is generated by Square and might not
            exactly match the

            time on your local machine.
          readOnly: true
        source_type:
          type: string
          description: >-
            The source type for this payment.


            Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`,
            `BUY_NOW_PAY_LATER`, `SQUARE_ACCOUNT`,

            `CASH` and `EXTERNAL`. For information about these payment source
            types,

            see [Take
            Payments](https://developer.squareup.com/docs/payments-api/take-payments).
          maxLength: 50
          readOnly: true
        card_details:
          $ref: '#/components/schemas/CardPaymentDetails'
          description: >-
            Details about a card payment. These details are only populated if
            the source_type is `CARD`.
          readOnly: true
        cash_details:
          $ref: '#/components/schemas/CashPaymentDetails'
          description: >-
            Details about a cash payment. These details are only populated if
            the source_type is `CASH`.
          nullable: true
        bank_account_details:
          $ref: '#/components/schemas/BankAccountPaymentDetails'
          description: >-
            Details about a bank account payment. These details are only
            populated if the source_type is `BANK_ACCOUNT`.
          readOnly: true
        external_details:
          $ref: '#/components/schemas/ExternalPaymentDetails'
          description: |-
            Details about an external payment. The details are only populated 
            if the `source_type` is `EXTERNAL`.
          readOnly: true
        wallet_details:
          $ref: '#/components/schemas/DigitalWalletDetails'
          description: |-
            Details about an wallet payment. The details are only populated 
            if the `source_type` is `WALLET`.
          readOnly: true
        buy_now_pay_later_details:
          $ref: '#/components/schemas/BuyNowPayLaterDetails'
          description: >-
            Details about a Buy Now Pay Later payment. The details are only
            populated

            if the `source_type` is `BUY_NOW_PAY_LATER`. For more information,
            see 

            [Afterpay
            Payments](https://developer.squareup.com/docs/payments-api/take-payments/afterpay-payments).
          readOnly: true
        square_account_details:
          $ref: '#/components/schemas/SquareAccountDetails'
          description: >-
            Details about a Square Account payment. The details are only
            populated

            if the `source_type` is `SQUARE_ACCOUNT`.
          readOnly: true
        location_id:
          type: string
          description: The ID of the location associated with the payment.
          maxLength: 50
          readOnly: true
        order_id:
          type: string
          description: The ID of the order associated with the payment.
          maxLength: 192
          readOnly: true
        reference_id:
          type: string
          description: |-
            An optional ID that associates the payment with an entity in
            another system.
          maxLength: 40
          readOnly: true
        customer_id:
          type: string
          description: >-
            The ID of the customer associated with the payment. If the ID is 

            not provided in the `CreatePayment` request that was used to create
            the `Payment`, 

            Square may use information in the request 

            (such as the billing and shipping address, email address, and
            payment source) 

            to identify a matching customer profile in the Customer Directory. 

            If found, the profile ID is used. If a profile is not found, the 

            API attempts to create an 

            [instant
            profile](https://developer.squareup.com/docs/customers-api/what-it-does#instant-profiles). 

            If the API cannot create an 

            instant profile (either because the seller has disabled it or the 

            seller's region prevents creating it), this field remains unset.
            Note that 

            this process is asynchronous and it may take some time before a 

            customer ID is added to the payment.
          maxLength: 191
          readOnly: true
        employee_id:
          type: string
          description: |-
            __Deprecated__: Use `Payment.team_member_id` instead.

            An optional ID of the employee associated with taking the payment.
          maxLength: 192
          readOnly: true
          x-release-status: DEPRECATED
        team_member_id:
          type: string
          description: >-
            An optional ID of the [TeamMember](entity:TeamMember) associated
            with taking the payment.
          maxLength: 192
          nullable: true
        refund_ids:
          type: array
          items:
            type: string
          description: A list of `refund_id`s identifying refunds for the payment.
          readOnly: true
        risk_evaluation:
          $ref: '#/components/schemas/RiskEvaluation'
          description: >-
            Provides information about the risk associated with the payment, as
            determined by Square.

            This field is present for payments to sellers that have opted in to
            receive risk

            evaluations.
          readOnly: true
          x-release-status: BETA
        terminal_checkout_id:
          type: string
          description: >-
            An optional ID for a Terminal checkout that is associated with the
            payment.
          readOnly: true
          x-release-status: BETA
        buyer_email_address:
          type: string
          description: The buyer's email address.
          maxLength: 255
          readOnly: true
        billing_address:
          $ref: '#/components/schemas/Address'
          description: The buyer's billing address.
          readOnly: true
        shipping_address:
          $ref: '#/components/schemas/Address'
          description: The buyer's shipping address.
          readOnly: true
        note:
          type: string
          description: An optional note to include when creating a payment.
          maxLength: 500
          readOnly: true
        statement_description_identifier:
          type: string
          description: >-
            Additional payment information that gets added to the customer's
            card statement

            as part of the statement description.


            Note that the `statement_description_identifier` might get truncated
            on the statement description

            to fit the required information including the Square identifier (SQ
            *) and the name of the

            seller taking the payment.
          readOnly: true
        capabilities:
          type: array
          items:
            type: string
          description: |-
            Actions that can be performed on this payment:
            - `EDIT_AMOUNT_UP` - The payment amount can be edited up.
            - `EDIT_AMOUNT_DOWN` - The payment amount can be edited down.
            - `EDIT_TIP_AMOUNT_UP` - The tip amount can be edited up.
            - `EDIT_TIP_AMOUNT_DOWN` - The tip amount can be edited down.
            - `EDIT_DELAY_ACTION` - The delay_action can be edited.
          readOnly: true
        receipt_number:
          type: string
          description: |-
            The payment's receipt number.
            The field is missing if a payment is canceled.
          maxLength: 4
          readOnly: true
        receipt_url:
          type: string
          description: |-
            The URL for the payment's receipt.
            The field is only populated for COMPLETED payments.
          maxLength: 255
          readOnly: true
        device_details:
          $ref: '#/components/schemas/DeviceDetails'
          description: Details about the device that took the payment.
          readOnly: true
        application_details:
          $ref: '#/components/schemas/ApplicationDetails'
          description: Details about the application that took the payment.
          readOnly: true
        is_offline_payment:
          type: boolean
          description: Whether or not this payment was taken offline.
          readOnly: true
        offline_payment_details:
          $ref: '#/components/schemas/OfflinePaymentDetails'
          description: Additional information about the payment if it was taken offline.
          readOnly: true
        version_token:
          type: string
          description: >-
            Used for optimistic concurrency. This opaque token identifies a
            specific version of the

            `Payment` object.
          nullable: true
    PaymentBalanceActivityAppFeeRefundDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
        refund_id:
          type: string
          description: The ID of the refund associated with this activity.
          nullable: true
        location_id:
          type: string
          description: >-
            The ID of the location of the merchant associated with the payment
            refund activity
          nullable: true
    PaymentBalanceActivityAppFeeRevenueDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
        location_id:
          type: string
          description: >-
            The ID of the location of the merchant associated with the payment
            activity
          nullable: true
    PaymentBalanceActivityAutomaticSavingsDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
        payout_id:
          type: string
          description: The ID of the payout associated with this activity.
          nullable: true
    PaymentBalanceActivityAutomaticSavingsReversedDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
        payout_id:
          type: string
          description: The ID of the payout associated with this activity.
          nullable: true
    PaymentBalanceActivityChargeDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
    PaymentBalanceActivityDepositFeeDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payout_id:
          type: string
          description: The ID of the payout that triggered this deposit fee activity.
          nullable: true
    PaymentBalanceActivityDepositFeeReversedDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payout_id:
          type: string
          description: The ID of the payout that triggered this deposit fee activity.
          nullable: true
    PaymentBalanceActivityDisputeDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
        dispute_id:
          type: string
          description: The ID of the dispute associated with this activity.
          nullable: true
    PaymentBalanceActivityFeeDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: >-
            The ID of the payment associated with this activity

            This will only be populated when a principal LedgerEntryToken is
            also populated.

            If the fee is independent (there is no principal LedgerEntryToken)
            then this will likely not

            be populated.
          nullable: true
    PaymentBalanceActivityFreeProcessingDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
    PaymentBalanceActivityHoldAdjustmentDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
    PaymentBalanceActivityOpenDisputeDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
        dispute_id:
          type: string
          description: The ID of the dispute associated with this activity.
          nullable: true
    PaymentBalanceActivityOtherAdjustmentDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
    PaymentBalanceActivityOtherDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
    PaymentBalanceActivityRefundDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
        refund_id:
          type: string
          description: The ID of the refund associated with this activity.
          nullable: true
    PaymentBalanceActivityReleaseAdjustmentDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
    PaymentBalanceActivityReserveHoldDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
    PaymentBalanceActivityReserveReleaseDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
    PaymentBalanceActivitySquareCapitalPaymentDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
    PaymentBalanceActivitySquareCapitalReversedPaymentDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
    PaymentBalanceActivitySquarePayrollTransferDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
    PaymentBalanceActivitySquarePayrollTransferReversedDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
    PaymentBalanceActivityTaxOnFeeDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
        tax_rate_description:
          type: string
          description: >-
            The description of the tax rate being applied. For example: "GST",
            "HST".
          nullable: true
    PaymentBalanceActivityThirdPartyFeeDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
    PaymentBalanceActivityThirdPartyFeeRefundDetail:
      type: object
      x-release-status: PUBLIC
      properties:
        payment_id:
          type: string
          description: The ID of the payment associated with this activity.
          nullable: true
        refund_id:
          type: string
          description: The public refund id associated with this activity.
          nullable: true
    PaymentLink:
      type: object
      x-release-status: PUBLIC
      required:
        - version
      properties:
        id:
          type: string
          description: The Square-assigned ID of the payment link.
          readOnly: true
        version:
          type: integer
          description: >-
            The Square-assigned version number, which is incremented each time
            an update is committed to the payment link.
          maximum: 65535
        description:
          type: string
          description: >-
            The optional description of the `payment_link` object.

            It is primarily for use by your application and is not used
            anywhere.
          maxLength: 4096
          nullable: true
        order_id:
          type: string
          description: The ID of the order associated with the payment link.
          maxLength: 192
          readOnly: true
        checkout_options:
          $ref: '#/components/schemas/CheckoutOptions'
          description: >-
            The checkout options configured for the payment link.

            For more information, see [Optional Checkout
            Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations).
          nullable: true
        pre_populated_data:
          $ref: '#/components/schemas/PrePopulatedData'
          description: |-
            Describes buyer data to prepopulate
            on the checkout page.
          nullable: true
        url:
          type: string
          description: The shortened URL of the payment link.
          maxLength: 255
          readOnly: true
        long_url:
          type: string
          description: The long URL of the payment link.
          maxLength: 255
          readOnly: true
        created_at:
          type: string
          description: The timestamp when the payment link was created, in RFC 3339 format.
        updated_at:
          type: string
          description: >-
            The timestamp when the payment link was last updated, in RFC 3339
            format.
        payment_note:
          type: string
          description: >-
            An optional note. After Square processes the payment, this note is
            added to the

            resulting `Payment`.
          maxLength: 500
          nullable: true
    PaymentLinkRelatedResources:
      type: object
      x-release-status: PUBLIC
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
          description: The order associated with the payment link.
          nullable: true
        subscription_plans:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: The subscription plan associated with the payment link.
          nullable: true
    PaymentOptions:
      type: object
      x-release-status: PUBLIC
      properties:
        autocomplete:
          type: boolean
          description: >-
            Indicates whether the `Payment` objects created from this
            `TerminalCheckout` are automatically

            `COMPLETED` or left in an `APPROVED` state for later modification.


            Default: true
          nullable: true
        delay_duration:
          type: string
          description: >-
            The duration of time after the payment's creation when Square
            automatically resolves the

            payment. This automatic resolution applies only to payments that do
            not reach a terminal state

            (`COMPLETED` or `CANCELED`) before the `delay_duration` time period.


            This parameter should be specified as a time duration, in RFC 3339
            format, with a minimum value

            of 1 minute and a maximum value of 36 hours. This feature is only
            supported for card payments,

            and all payments will be considered card-present.


            This parameter can only be set for a delayed capture payment
            (`autocomplete=false`). For more

            information, see [Delayed
            Capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold).


            Default: "PT36H" (36 hours) from the creation time
          nullable: true
        accept_partial_authorization:
          type: boolean
          description: >-
            If set to `true` and charging a Square Gift Card, a payment might be
            returned with

            `amount_money` equal to less than what was requested. For example, a
            request for $20 when charging

            a Square Gift Card with a balance of $5 results in an APPROVED
            payment of $5. You might choose

            to prompt the buyer for an additional payment to cover the remainder
            or cancel the Gift Card

            payment.


            This parameter can only be set for a delayed capture payment
            (`autocomplete=false`).


            For more information, see [Take Partial
            Payments](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/partial-payments-with-gift-cards).


            Default: false
          nullable: true
        delay_action:
          $ref: '#/components/schemas/PaymentOptionsDelayAction'
          description: >-
            The action to be applied to the `Payment` when the delay_duration
            has elapsed.

            The action must be CANCEL or COMPLETE.


            The action cannot be set to COMPLETE if an `order_id` is present on
            the TerminalCheckout.


            This parameter can only be set for a delayed capture payment
            (`autocomplete=false`). For more

            information, see [Delayed
            Capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture#time-threshold).


            Default: CANCEL

            See [DelayAction](#type-delayaction) for possible values
          x-release-status: BETA
          nullable: true
    PaymentOptionsDelayAction:
      type: string
      enum:
        - CANCEL
        - COMPLETE
      x-enum-elements:
        - name: CANCEL
          description: >-
            Indicates that the payment should be automatically canceled when the
            delay duration

            elapses.
        - name: COMPLETE
          description: >-
            Indicates that the payment should be automatically completed when
            the delay duration

            elapses.
      description: >-
        Describes the action to be applied to a delayed capture payment when the
        delay_duration

        has elapsed.
      x-release-status: BETA
    PaymentRefund:
      type: object
      description: >-
        Represents a refund of a payment made using Square. Contains information
        about

        the original payment and the amount of money refunded.
      x-release-status: PUBLIC
      required:
        - id
        - amount_money
      properties:
        id:
          type: string
          description: The unique ID for this refund, generated by Square.
          minLength: 1
          maxLength: 255
        status:
          type: string
          description: |-
            The refund's status:
            - `PENDING` - Awaiting approval.
            - `COMPLETED` - Successfully completed.
            - `REJECTED` - The refund was rejected.
            - `FAILED` - An error occurred.
          maxLength: 50
          nullable: true
        location_id:
          type: string
          description: >-
            The location ID associated with the payment this refund is attached
            to.
          maxLength: 50
          nullable: true
        unlinked:
          type: boolean
          description: >-
            Flag indicating whether or not the refund is linked to an existing
            payment in Square.
          readOnly: true
        destination_type:
          type: string
          description: >-
            The destination type for this refund.


            Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`,
            `BUY_NOW_PAY_LATER`, `CASH`,

            `EXTERNAL`, and `SQUARE_ACCOUNT`.
          maxLength: 50
          nullable: true
        destination_details:
          $ref: '#/components/schemas/DestinationDetails'
          description: >-
            Contains information about the refund destination. This field is
            populated only if

            `destination_id` is defined in the `RefundPayment` request.
          readOnly: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money refunded. This amount is specified in the
            smallest denomination

            of the applicable currency (for example, US dollar amounts are
            specified in cents).
        app_fee_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money the application developer contributed to help
            cover the refunded amount.

            This amount is specified in the smallest denomination of the
            applicable currency (for example,

            US dollar amounts are specified in cents). For more information, see

            [Working with Monetary
            Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).
          nullable: true
        processing_fee:
          type: array
          items:
            $ref: '#/components/schemas/ProcessingFee'
          description: >-
            Processing fees and fee adjustments assessed by Square for this
            refund.
          nullable: true
        payment_id:
          type: string
          description: The ID of the payment associated with this refund.
          maxLength: 192
          nullable: true
        order_id:
          type: string
          description: The ID of the order associated with the refund.
          maxLength: 192
          nullable: true
        reason:
          type: string
          description: The reason for the refund.
          maxLength: 192
          nullable: true
        created_at:
          type: string
          description: The timestamp of when the refund was created, in RFC 3339 format.
          maxLength: 32
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp of when the refund was last updated, in RFC 3339
            format.
          maxLength: 32
          readOnly: true
        team_member_id:
          type: string
          description: >-
            An optional ID of the team member associated with taking the
            payment.
          maxLength: 192
          readOnly: true
        terminal_refund_id:
          type: string
          description: An optional ID for a Terminal refund.
          readOnly: true
          x-release-status: BETA
    PaymentSortField:
      type: string
      enum:
        - CREATED_AT
        - OFFLINE_CREATED_AT
        - UPDATED_AT
      x-enum-elements:
        - name: CREATED_AT
          description: ''
        - name: OFFLINE_CREATED_AT
          description: ''
        - name: UPDATED_AT
          description: ''
      x-release-status: PUBLIC
    Payout:
      type: object
      description: >-
        An accounting of the amount owed the seller and record of the actual
        transfer to their

        external bank account or to the Square balance.
      x-release-status: PUBLIC
      required:
        - id
        - location_id
      properties:
        id:
          type: string
          description: A unique ID for the payout.
          minLength: 1
        status:
          $ref: '#/components/schemas/PayoutStatus'
          description: |-
            Indicates the payout status.
            See [PayoutStatus](#type-payoutstatus) for possible values
          nullable: true
        location_id:
          type: string
          description: The ID of the location associated with the payout.
          minLength: 1
        created_at:
          type: string
          description: >-
            The timestamp of when the payout was created and submitted for
            deposit to the seller's banking destination, in RFC 3339 format.
        updated_at:
          type: string
          description: >-
            The timestamp of when the payout was last updated, in RFC 3339
            format.
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money involved in the payout. A positive amount
            indicates a deposit, and a negative amount indicates a withdrawal.
            This amount is never zero.
          nullable: true
        destination:
          $ref: '#/components/schemas/Destination'
          description: >-
            Information about the banking destination (such as a bank account,
            Square checking account, or debit card)

            against which the payout was made.
          nullable: true
        version:
          type: integer
          description: >-
            The version number, which is incremented each time an update is made
            to this payout record.

            The version number helps developers receive event notifications or
            feeds out of order.
        type:
          $ref: '#/components/schemas/PayoutType'
          description: |-
            Indicates the payout type.
            See [PayoutType](#type-payouttype) for possible values
          nullable: true
        payout_fee:
          type: array
          items:
            $ref: '#/components/schemas/PayoutFee'
          description: >-
            A list of transfer fees and any taxes on the fees assessed by Square
            for this payout.
          nullable: true
        arrival_date:
          type: string
          description: >-
            The calendar date, in ISO 8601 format (YYYY-MM-DD), when the payout
            is due to arrive in the sellers banking destination.
          nullable: true
        end_to_end_id:
          type: string
          description: >-
            A unique ID for each `Payout` object that might also appear on the
            sellers bank statement. You can use this ID to automate the process
            of reconciling each payout with the corresponding line item on the
            bank statement.
          nullable: true
    PayoutEntry:
      type: object
      description: >-
        One or more PayoutEntries that make up a Payout. Each one has a date,
        amount, and type of activity.

        The total amount of the payout will equal the sum of the payout entries
        for a batch payout
      x-release-status: PUBLIC
      required:
        - id
        - payout_id
      properties:
        id:
          type: string
          description: A unique ID for the payout entry.
          minLength: 1
        payout_id:
          type: string
          description: The ID of the payout entries associated payout.
          minLength: 1
        effective_at:
          type: string
          description: >-
            The timestamp of when the payout entry affected the balance, in RFC
            3339 format.
          nullable: true
        type:
          $ref: '#/components/schemas/ActivityType'
          description: |-
            The type of activity associated with this payout entry.
            See [ActivityType](#type-activitytype) for possible values
          nullable: true
        gross_amount_money:
          $ref: '#/components/schemas/Money'
          description: The amount of money involved in this payout entry.
          nullable: true
        fee_amount_money:
          $ref: '#/components/schemas/Money'
          description: The amount of Square fees associated with this payout entry.
          nullable: true
        net_amount_money:
          $ref: '#/components/schemas/Money'
          description: The net proceeds from this transaction after any fees.
          nullable: true
        type_app_fee_revenue_details:
          $ref: '#/components/schemas/PaymentBalanceActivityAppFeeRevenueDetail'
          description: Details of any developer app fee revenue generated on a payment.
          nullable: true
        type_app_fee_refund_details:
          $ref: '#/components/schemas/PaymentBalanceActivityAppFeeRefundDetail'
          description: Details of a refund for an app fee on a payment.
          nullable: true
        type_automatic_savings_details:
          $ref: '#/components/schemas/PaymentBalanceActivityAutomaticSavingsDetail'
          description: >-
            Details of any automatic transfer from the payment processing
            balance to the Square Savings account. These are, generally,
            proportional to the merchant's sales.
          nullable: true
        type_automatic_savings_reversed_details:
          $ref: >-
            #/components/schemas/PaymentBalanceActivityAutomaticSavingsReversedDetail
          description: >-
            Details of any automatic transfer from the Square Savings account
            back to the processing balance. These are, generally, proportional
            to the merchant's refunds.
          nullable: true
        type_charge_details:
          $ref: '#/components/schemas/PaymentBalanceActivityChargeDetail'
          description: Details of credit card payment captures.
          nullable: true
        type_deposit_fee_details:
          $ref: '#/components/schemas/PaymentBalanceActivityDepositFeeDetail'
          description: >-
            Details of any fees involved with deposits such as for instant
            deposits.
          nullable: true
        type_deposit_fee_reversed_details:
          $ref: '#/components/schemas/PaymentBalanceActivityDepositFeeReversedDetail'
          description: >-
            Details of any reversal or refund of fees involved with deposits
            such as for instant deposits.
          nullable: true
        type_dispute_details:
          $ref: '#/components/schemas/PaymentBalanceActivityDisputeDetail'
          description: Details of any balance change due to a dispute event.
          nullable: true
        type_fee_details:
          $ref: '#/components/schemas/PaymentBalanceActivityFeeDetail'
          description: Details of adjustments due to the Square processing fee.
          nullable: true
        type_free_processing_details:
          $ref: '#/components/schemas/PaymentBalanceActivityFreeProcessingDetail'
          description: >-
            Square offers Free Payments Processing for a variety of business
            scenarios including seller referral or when Square wants to
            apologize for a bug, customer service, repricing complication, and
            so on. This entry represents details of any credit to the merchant
            for the purposes of Free Processing.
          nullable: true
        type_hold_adjustment_details:
          $ref: '#/components/schemas/PaymentBalanceActivityHoldAdjustmentDetail'
          description: >-
            Details of any adjustment made by Square related to the holding or
            releasing of a payment.
          nullable: true
        type_open_dispute_details:
          $ref: '#/components/schemas/PaymentBalanceActivityOpenDisputeDetail'
          description: Details of any open disputes.
          nullable: true
        type_other_details:
          $ref: '#/components/schemas/PaymentBalanceActivityOtherDetail'
          description: >-
            Details of any other type that does not belong in the rest of the
            types.
          nullable: true
        type_other_adjustment_details:
          $ref: '#/components/schemas/PaymentBalanceActivityOtherAdjustmentDetail'
          description: >-
            Details of any other type of adjustments that don't fall under
            existing types.
          nullable: true
        type_refund_details:
          $ref: '#/components/schemas/PaymentBalanceActivityRefundDetail'
          description: Details of a refund for an existing card payment.
          nullable: true
        type_release_adjustment_details:
          $ref: '#/components/schemas/PaymentBalanceActivityReleaseAdjustmentDetail'
          description: Details of fees released for adjustments.
          nullable: true
        type_reserve_hold_details:
          $ref: '#/components/schemas/PaymentBalanceActivityReserveHoldDetail'
          description: Details of fees paid for funding risk reserve.
          nullable: true
        type_reserve_release_details:
          $ref: '#/components/schemas/PaymentBalanceActivityReserveReleaseDetail'
          description: Details of fees released from risk reserve.
          nullable: true
        type_square_capital_payment_details:
          $ref: >-
            #/components/schemas/PaymentBalanceActivitySquareCapitalPaymentDetail
          description: >-
            Details of capital merchant cash advance (MCA) assessments. These
            are, generally, proportional to the merchant's sales but may be
            issued for other reasons related to the MCA.
          nullable: true
        type_square_capital_reversed_payment_details:
          $ref: >-
            #/components/schemas/PaymentBalanceActivitySquareCapitalReversedPaymentDetail
          description: >-
            Details of capital merchant cash advance (MCA) assessment refunds.
            These are, generally, proportional to the merchant's refunds but may
            be issued for other reasons related to the MCA.
          nullable: true
        type_tax_on_fee_details:
          $ref: '#/components/schemas/PaymentBalanceActivityTaxOnFeeDetail'
          description: Details of tax paid on fee amounts.
          nullable: true
        type_third_party_fee_details:
          $ref: '#/components/schemas/PaymentBalanceActivityThirdPartyFeeDetail'
          description: Details of fees collected by a 3rd party platform.
          nullable: true
        type_third_party_fee_refund_details:
          $ref: '#/components/schemas/PaymentBalanceActivityThirdPartyFeeRefundDetail'
          description: Details of refunded fees from a 3rd party platform.
          nullable: true
        type_square_payroll_transfer_details:
          $ref: >-
            #/components/schemas/PaymentBalanceActivitySquarePayrollTransferDetail
          description: >-
            Details of a payroll payment that was transferred to a team members
            bank account.
          nullable: true
        type_square_payroll_transfer_reversed_details:
          $ref: >-
            #/components/schemas/PaymentBalanceActivitySquarePayrollTransferReversedDetail
          description: >-
            Details of a payroll payment to a team members bank account that
            was deposited back to the sellers account by Square.
          nullable: true
    PayoutFee:
      type: object
      description: Represents a payout fee that can incur as part of a payout.
      x-release-status: PUBLIC
      properties:
        amount_money:
          $ref: '#/components/schemas/Money'
          description: The money amount of the payout fee.
          nullable: true
        effective_at:
          type: string
          description: The timestamp of when the fee takes effect, in RFC 3339 format.
          nullable: true
        type:
          $ref: '#/components/schemas/PayoutFeeType'
          description: |-
            The type of fee assessed as part of the payout.
            See [PayoutFeeType](#type-payoutfeetype) for possible values
          nullable: true
    PayoutFeeType:
      type: string
      enum:
        - TRANSFER_FEE
        - TAX_ON_TRANSFER_FEE
      x-enum-elements:
        - name: TRANSFER_FEE
          description: Fee type associated with transfers.
        - name: TAX_ON_TRANSFER_FEE
          description: Taxes associated with the transfer fee.
      description: Represents the type of payout fee that can incur as part of a payout.
      x-release-status: PUBLIC
    PayoutStatus:
      type: string
      enum:
        - SENT
        - FAILED
        - PAID
      x-enum-elements:
        - name: SENT
          description: >-
            Indicates that the payout was successfully sent to the banking
            destination.
        - name: FAILED
          description: Indicates that the payout was rejected by the banking destination.
        - name: PAID
          description: Indicates that the payout has successfully completed.
      description: Payout status types
      x-release-status: PUBLIC
    PayoutType:
      type: string
      enum:
        - BATCH
        - SIMPLE
      x-enum-elements:
        - name: BATCH
          description: >-
            Payouts that include a list of payout entries that can be considered
            settled.
        - name: SIMPLE
          description: >-
            Payouts that do not have any payout entries associated with them and
            will

            show up as one of the payout entries in a future BATCH payout.
      description: >-
        The type of payout: BATCH or SIMPLE.

        BATCH payouts include a list of payout entries that can be considered
        settled.

        SIMPLE payouts do not have any payout entries associated with them

        and will show up as one of the payout entries in a future BATCH payout.
      x-release-status: PUBLIC
    Phase:
      type: object
      description: >-
        Represents a phase, which can override subscription phases as defined by
        plan_id
      x-release-status: PUBLIC
      properties:
        uid:
          type: string
          description: id of subscription phase
          nullable: true
        ordinal:
          type: integer
          description: index of phase in total subscription plan
          format: int64
          nullable: true
        order_template_id:
          type: string
          description: id of order to be used in billing
          nullable: true
        plan_phase_uid:
          type: string
          description: the uid from the plan's phase in catalog
          nullable: true
    PhaseInput:
      type: object
      description: Represents the arguments used to construct a new phase.
      x-release-status: PUBLIC
      required:
        - ordinal
      properties:
        ordinal:
          type: integer
          description: index of phase in total subscription plan
          format: int64
        order_template_id:
          type: string
          description: id of order to be used in billing
          nullable: true
    PrePopulatedData:
      type: object
      description: >-
        Describes buyer data to prepopulate in the payment form.

        For more information,

        see [Optional Checkout
        Configurations](https://developer.squareup.com/docs/checkout-api/optional-checkout-configurations).
      x-release-status: PUBLIC
      properties:
        buyer_email:
          type: string
          description: The buyer email to prepopulate in the payment form.
          maxLength: 256
          nullable: true
        buyer_phone_number:
          type: string
          description: The buyer phone number to prepopulate in the payment form.
          maxLength: 17
          nullable: true
        buyer_address:
          $ref: '#/components/schemas/Address'
          description: The buyer address to prepopulate in the payment form.
          nullable: true
    ProcessingFee:
      type: object
      description: Represents the Square processing fee.
      x-release-status: PUBLIC
      properties:
        effective_at:
          type: string
          description: The timestamp of when the fee takes effect, in RFC 3339 format.
          nullable: true
        type:
          type: string
          description: >-
            The type of fee assessed or adjusted. The fee type can be `INITIAL`
            or `ADJUSTMENT`.
          nullable: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The fee amount, which might be negative, that is assessed or
            adjusted by Square.


            Positive values represent funds being assessed, while negative
            values represent

            funds being returned.
          nullable: true
    Product:
      type: string
      enum:
        - SQUARE_POS
        - EXTERNAL_API
        - BILLING
        - APPOINTMENTS
        - INVOICES
        - ONLINE_STORE
        - PAYROLL
        - DASHBOARD
        - ITEM_LIBRARY_IMPORT
        - OTHER
      x-enum-elements:
        - name: SQUARE_POS
          description: Square Point of Sale application.
        - name: EXTERNAL_API
          description: Square Connect APIs (for example, Orders API or Checkout API).
        - name: BILLING
          description: A Square subscription (various products).
        - name: APPOINTMENTS
          description: Square Appointments.
        - name: INVOICES
          description: Square Invoices.
        - name: ONLINE_STORE
          description: Square Online Store.
        - name: PAYROLL
          description: Square Payroll.
        - name: DASHBOARD
          description: Square Dashboard.
        - name: ITEM_LIBRARY_IMPORT
          description: Item Library Import.
        - name: OTHER
          description: A Square product that does not match any other value.
      description: Indicates the Square product used to generate a change.
      x-release-status: PUBLIC
    ProductType:
      type: string
      enum:
        - TERMINAL_API
      x-enum-elements:
        - name: TERMINAL_API
          description: ''
      x-release-status: PUBLIC
    PublishInvoiceRequest:
      type: object
      description: Describes a `PublishInvoice` request.
      x-release-status: PUBLIC
      required:
        - version
      properties:
        version:
          type: integer
          description: >-
            The version of the [invoice](entity:Invoice) to publish.

            This must match the current version of the invoice; otherwise, the
            request is rejected.
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies the `PublishInvoice` request. If you
            do not 

            provide `idempotency_key` (or provide an empty string as the value),
            the endpoint 

            treats each request as independent.


            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 128
          nullable: true
      example:
        idempotency_key: 32da42d0-1997-41b0-826b-f09464fc2c2e
        version: 1
    PublishInvoiceResponse:
      type: object
      description: Describes a `PublishInvoice` response.
      x-release-status: PUBLIC
      properties:
        invoice:
          $ref: '#/components/schemas/Invoice'
          description: The published invoice.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example:
        invoice:
          accepted_payment_methods:
            bank_account: false
            buy_now_pay_later: false
            card: true
            cash_app_pay: false
            square_gift_card: false
          created_at: '2020-06-18T17:45:13Z'
          custom_fields:
            - label: Event Reference Number
              placement: ABOVE_LINE_ITEMS
              value: 'Ref. #1234'
            - label: Terms of Service
              placement: BELOW_LINE_ITEMS
              value: The terms of service are...
          delivery_method: EMAIL
          description: We appreciate your business!
          id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
          invoice_number: inv-100
          location_id: ES0RJRZYEC39A
          order_id: CAISENgvlJ6jLWAzERDzjyHVybY
          payment_requests:
            - automatic_payment_source: NONE
              computed_amount_money:
                amount: 10000
                currency: USD
              due_date: '2030-01-24'
              reminders:
                - message: Your invoice is due tomorrow
                  relative_scheduled_days: -1
                  status: PENDING
                  uid: beebd363-e47f-4075-8785-c235aaa7df11
              request_type: BALANCE
              tipping_enabled: true
              total_completed_amount_money:
                amount: 0
                currency: USD
              uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355
          primary_recipient:
            customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4
            email_address: Amelia.Earhart@example.com
            family_name: Earhart
            given_name: Amelia
            phone_number: 1-212-555-4240
          public_url: https://squareup.com/pay-invoice/inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
          sale_or_service_date: '2030-01-24'
          scheduled_at: '2030-01-13T10:00:00Z'
          status: SCHEDULED
          store_payment_method_enabled: false
          timezone: America/Los_Angeles
          title: Event Planning Services
          updated_at: '2020-06-18T18:23:11Z'
          version: 1
    QrCodeOptions:
      type: object
      description: Fields to describe the action that displays QR-Codes.
      x-release-status: BETA
      required:
        - title
        - body
        - barcode_contents
      properties:
        title:
          type: string
          description: The title text to display in the QR code flow on the Terminal.
          minLength: 1
          maxLength: 250
        body:
          type: string
          description: The body text to display in the QR code flow on the Terminal.
          minLength: 1
          maxLength: 10000
        barcode_contents:
          type: string
          description: |-
            The text representation of the data to show in the QR code
            as UTF8-encoded data.
          minLength: 1
          maxLength: 1024
    QuantityRatio:
      type: object
      description: A whole number or unreduced fractional ratio.
      x-release-status: BETA
      properties:
        quantity:
          type: integer
          description: The whole or fractional quantity as the numerator.
          nullable: true
        quantity_denominator:
          type: integer
          description: >-
            The whole or fractional quantity as the denominator.

            With fractional quantity this field is the denominator and quantity
            is the numerator.

            The default value is `1`. For example, when `quantity=3` and
            `quantity_denominator` is unspecified,

            the quantity ratio is `3` or `3/1`.
          nullable: true
    QuickPay:
      type: object
      description: >-
        Describes an ad hoc item and price to generate a quick pay checkout
        link.

        For more information,

        see [Quick Pay
        Checkout](https://developer.squareup.com/docs/checkout-api/quick-pay-checkout).
      x-release-status: PUBLIC
      required:
        - name
        - price_money
        - location_id
      properties:
        name:
          type: string
          description: >-
            The ad hoc item name. In the resulting `Order`, this name appears as
            the line item name.
          minLength: 1
          maxLength: 255
        price_money:
          $ref: '#/components/schemas/Money'
          description: The price of the item.
        location_id:
          type: string
          description: The ID of the business location the checkout is associated with.
    Range:
      type: object
      description: >-
        The range of a number value between the specified lower and upper
        bounds.
      x-release-status: PUBLIC
      properties:
        min:
          type: string
          description: >-
            The lower bound of the number range. At least one of `min` or `max`
            must be specified.

            If unspecified, the results will have no minimum value.
          nullable: true
        max:
          type: string
          description: >-
            The upper bound of the number range. At least one of `min` or `max`
            must be specified.

            If unspecified, the results will have no maximum value.
          nullable: true
    ReceiptOptions:
      type: object
      description: Describes receipt action fields.
      x-release-status: BETA
      required:
        - payment_id
      properties:
        payment_id:
          type: string
          description: The reference to the Square payment ID for the receipt.
        print_only:
          type: boolean
          description: >-
            Instructs the device to print the receipt without displaying the
            receipt selection screen.

            Requires `printer_enabled` set to true.

            Defaults to false.
          nullable: true
        is_duplicate:
          type: boolean
          description: |-
            Identify the receipt as a reprint rather than an original receipt.
            Defaults to false.
          nullable: true
    RedeemLoyaltyRewardRequest:
      type: object
      description: A request to redeem a loyalty reward.
      x-release-status: PUBLIC
      x-params-example: '?reward_id=9f18ac21-233a-31c3-be77-b45840f5a810'
      required:
        - idempotency_key
        - location_id
      properties:
        idempotency_key:
          type: string
          description: |-
            A unique string that identifies this `RedeemLoyaltyReward` request. 
            Keys can be any valid string, but must be unique for every request.
          minLength: 1
          maxLength: 128
        location_id:
          type: string
          description: >-
            The ID of the [location](entity:Location) where the reward is
            redeemed.
          minLength: 1
      example:
        idempotency_key: 98adc7f7-6963-473b-b29c-f3c9cdd7d994
        location_id: P034NEENMD09F
    RedeemLoyaltyRewardResponse:
      type: object
      description: >-
        A response that includes the `LoyaltyEvent` published for redeeming the
        reward.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        event:
          $ref: '#/components/schemas/LoyaltyEvent'
          description: The `LoyaltyEvent` for redeeming the reward.
      example:
        event:
          created_at: '2020-05-08T21:56:00Z'
          id: 67377a6e-dbdc-369d-aa16-2e7ed422e71f
          location_id: P034NEENMD09F
          loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
          redeem_reward:
            loyalty_program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
            reward_id: 9f18ac21-233a-31c3-be77-b45840f5a810
          source: LOYALTY_API
          type: REDEEM_REWARD
    Refund:
      type: object
      description: Represents a refund processed for a Square transaction.
      x-release-status: PUBLIC
      required:
        - id
        - location_id
        - tender_id
        - reason
        - amount_money
        - status
      properties:
        id:
          type: string
          description: The refund's unique ID.
          maxLength: 255
        location_id:
          type: string
          description: The ID of the refund's associated location.
          maxLength: 50
        transaction_id:
          type: string
          description: The ID of the transaction that the refunded tender is part of.
          maxLength: 192
          nullable: true
        tender_id:
          type: string
          description: The ID of the refunded tender.
          maxLength: 192
        created_at:
          type: string
          description: The timestamp for when the refund was created, in RFC 3339 format.
          maxLength: 32
          readOnly: true
        reason:
          type: string
          description: The reason for the refund being issued.
          maxLength: 192
        amount_money:
          $ref: '#/components/schemas/Money'
          description: The amount of money refunded to the buyer.
        status:
          $ref: '#/components/schemas/RefundStatus'
          description: |-
            The current status of the refund (`PENDING`, `APPROVED`, `REJECTED`,
            or `FAILED`).
            See [RefundStatus](#type-refundstatus) for possible values
        processing_fee_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of Square processing fee money refunded to the
            *merchant*.
          nullable: true
        additional_recipients:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalRecipient'
          description: >-
            Additional recipients (other than the merchant) receiving a portion
            of this refund.

            For example, fees assessed on a refund of a purchase by a third
            party integration.
          x-release-status: DEPRECATED
          nullable: true
    RefundPaymentRequest:
      type: object
      description: >-
        Describes a request to refund a payment using
        [RefundPayment](api-endpoint:Refunds-RefundPayment).
      x-release-status: PUBLIC
      required:
        - idempotency_key
        - amount_money
      properties:
        idempotency_key:
          type: string
          description: >2-
             A unique string that identifies this `RefundPayment` request. The key can be any valid string
            but must be unique for every `RefundPayment` request.


            Keys are limited to a max of 45 characters - however, the number of
            allowed characters might be

            less than 45, if multi-byte characters are used.


            For more information, see
            [Idempotency](https://developer.squareup.com/docs/working-with-apis/idempotency).
          minLength: 1
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money to refund.


            This amount cannot be more than the `total_money` value of the
            payment minus the total

            amount of all previously completed refunds for this payment.


            This amount must be specified in the smallest denomination of the
            applicable currency

            (for example, US dollar amounts are specified in cents). For more
            information, see

            [Working with Monetary
            Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).


            The currency code must match the currency associated with the
            business

            that is charging the card.
        app_fee_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money the developer contributes to help cover the
            refunded amount.

            This amount is specified in the smallest denomination of the
            applicable currency (for example,

            US dollar amounts are specified in cents).


            The value cannot be more than the `amount_money`.


            You can specify this parameter in a refund request only if the same
            parameter was also included

            when taking the payment. This is part of the application fee
            scenario the API supports. For more

            information, see [Take Payments and Collect
            Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).


            To set this field, `PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS` OAuth
            permission is required.

            For more information, see
            [Permissions](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees#permissions).
          x-release-status: BETA
          nullable: true
        payment_id:
          type: string
          description: |-
            The unique ID of the payment being refunded.
            Required when unlinked=false, otherwise must not be set.
          nullable: true
        destination_id:
          type: string
          description: >-
            The ID indicating where funds will be refunded to. Required for
            unlinked refunds. For more

            information, see [Process an Unlinked
            Refund](https://developer.squareup.com/docs/refunds-api/unlinked-refunds).


            For refunds linked to Square payments, `destination_id` is usually
            omitted; in this case, funds

            will be returned to the original payment source. The field may be
            specified in order to request

            a cross-method refund to a gift card. For more information,

            see [Cross-method refunds to gift
            cards](https://developer.squareup.com/docs/payments-api/refund-payments#cross-method-refunds-to-gift-cards).
          nullable: true
        unlinked:
          type: boolean
          description: >-
            Indicates that the refund is not linked to a Square payment.

            If set to true, `destination_id` and `location_id` must be supplied
            while `payment_id` must not

            be provided.
          nullable: true
        location_id:
          type: string
          description: |-
            The location ID associated with the unlinked refund.
            Required for requests specifying `unlinked=true`.
            Otherwise, if included when `unlinked=false`, will throw an error.
          maxLength: 50
          nullable: true
        customer_id:
          type: string
          description: >-
            The [Customer](entity:Customer) ID of the customer associated with
            the refund.

            This is required if the `destination_id` refers to a card on file
            created using the Cards

            API. Only allowed when `unlinked=true`.
          nullable: true
        reason:
          type: string
          description: A description of the reason for the refund.
          maxLength: 192
          nullable: true
        payment_version_token:
          type: string
          description: >2-
             Used for optimistic concurrency. This opaque token identifies the current `Payment`
            version that the caller expects. If the server has a different
            version of the Payment,

            the update fails and a response with a VERSION_MISMATCH error is
            returned.

            If the versions match, or the field is not provided, the refund
            proceeds as normal.
          x-release-status: BETA
          nullable: true
        team_member_id:
          type: string
          description: >-
            An optional [TeamMember](entity:TeamMember) ID to associate with
            this refund.
          maxLength: 192
          nullable: true
        cash_details:
          $ref: '#/components/schemas/DestinationDetailsCashRefundDetails'
          description: >-
            Additional details required when recording an unlinked cash refund
            (`destination_id` is CASH).
          nullable: true
        external_details:
          $ref: '#/components/schemas/DestinationDetailsExternalRefundDetails'
          description: >-
            Additional details required when recording an unlinked external
            refund

            (`destination_id` is EXTERNAL).
          nullable: true
      example:
        amount_money:
          amount: 1000
          currency: USD
        app_fee_money:
          amount: 10
          currency: USD
        idempotency_key: 9b7f2dcf-49da-4411-b23e-a2d6af21333a
        payment_id: R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY
        reason: Example
    RefundPaymentResponse:
      type: object
      description: >-
        Defines the response returned by

        [RefundPayment](api-endpoint:Refunds-RefundPayment).


        If there are errors processing the request, the `refund` field might not
        be

        present, or it might be present with a status of `FAILED`.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        refund:
          $ref: '#/components/schemas/PaymentRefund'
          description: The successfully created `PaymentRefund`.
      example:
        refund:
          amount_money:
            amount: 1000
            currency: USD
          app_fee_money:
            amount: 10
            currency: USD
          created_at: '2021-10-13T21:23:19.116Z'
          id: >-
            R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY_KlWP8IC1557ddwc9QWTKrCVU6m0JXDz15R2Qym5eQfR
          location_id: L88917AVBK2S5
          order_id: 1JLEUZeEooAIX8HMqm9kvWd69aQZY
          payment_id: R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY
          reason: Example
          status: PENDING
          updated_at: '2021-10-13T21:23:19.508Z'
    RefundStatus:
      type: string
      enum:
        - PENDING
        - APPROVED
        - REJECTED
        - FAILED
      x-enum-elements:
        - name: PENDING
          description: The refund is pending.
        - name: APPROVED
          description: The refund has been approved by Square.
        - name: REJECTED
          description: The refund has been rejected by Square.
        - name: FAILED
          description: The refund failed.
      description: Indicates a refund's current status.
      x-release-status: PUBLIC
    RegisterDomainRequest:
      type: object
      description: >-
        Defines the parameters that can be included in the body of

        a request to the [RegisterDomain](api-endpoint:ApplePay-RegisterDomain)
        endpoint.
      x-release-status: PUBLIC
      required:
        - domain_name
      properties:
        domain_name:
          type: string
          description: >-
            A domain name as described in RFC-1034 that will be registered with
            ApplePay.
          minLength: 1
          maxLength: 255
      example:
        domain_name: example.com
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/ApplePay/RegisterDomain/RegisterDomainRequest.csharp
        java: /sdk_samples/ApplePay/RegisterDomain/RegisterDomainRequest.java
        javascript: /sdk_samples/ApplePay/RegisterDomain/RegisterDomainRequest.javascript
        php: /sdk_samples/ApplePay/RegisterDomain/RegisterDomainRequest.php
        python: /sdk_samples/ApplePay/RegisterDomain/RegisterDomainRequest.python
        ruby: /sdk_samples/ApplePay/RegisterDomain/RegisterDomainRequest.ruby
    RegisterDomainResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [RegisterDomain](api-endpoint:ApplePay-RegisterDomain)
        endpoint.


        Either `errors` or `status` are present in a given response (never
        both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        status:
          $ref: '#/components/schemas/RegisterDomainResponseStatus'
          description: >-
            The status of the domain registration.


            See
            [RegisterDomainResponseStatus](entity:RegisterDomainResponseStatus)
            for possible values.

            See
            [RegisterDomainResponseStatus](#type-registerdomainresponsestatus)
            for possible values
      example:
        status: VERIFIED
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/ApplePay/RegisterDomain/RegisterDomainResponse.csharp
        java: /sdk_samples/ApplePay/RegisterDomain/RegisterDomainResponse.java
        javascript: /sdk_samples/ApplePay/RegisterDomain/RegisterDomainResponse.javascript
        php: /sdk_samples/ApplePay/RegisterDomain/RegisterDomainResponse.php
        python: /sdk_samples/ApplePay/RegisterDomain/RegisterDomainResponse.python
        ruby: /sdk_samples/ApplePay/RegisterDomain/RegisterDomainResponse.ruby
    RegisterDomainResponseStatus:
      type: string
      enum:
        - PENDING
        - VERIFIED
      x-enum-elements:
        - name: PENDING
          description: The domain is added, but not verified.
        - name: VERIFIED
          description: >-
            The domain is added and verified. It can be used to accept Apple Pay
            transactions.
      description: The status of the domain registration.
      x-release-status: PUBLIC
    RemoveGroupFromCustomerRequest:
      type: object
      description: >-
        Defines the fields that are included in the request body of

        a request to the
        [RemoveGroupFromCustomer](api-endpoint:Customers-RemoveGroupFromCustomer)
        endpoint.
      x-release-status: PUBLIC
      properties: {}
      example: {}
    RemoveGroupFromCustomerResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [RemoveGroupFromCustomer](api-endpoint:Customers-RemoveGroupFromCustomer)

        endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
    ResumeSubscriptionRequest:
      type: object
      description: >-
        Defines input parameters in a request to the

        [ResumeSubscription](api-endpoint:Subscriptions-ResumeSubscription)
        endpoint.
      x-release-status: PUBLIC
      properties:
        resume_effective_date:
          type: string
          description: The `YYYY-MM-DD`-formatted date when the subscription reactivated.
          x-release-status: BETA
          nullable: true
        resume_change_timing:
          $ref: '#/components/schemas/ChangeTiming'
          description: |-
            The timing to resume a subscription, relative to the specified
            `resume_effective_date` attribute value.
            See [ChangeTiming](#type-changetiming) for possible values
          x-release-status: BETA
          nullable: true
    ResumeSubscriptionResponse:
      type: object
      description: >-
        Defines output parameters in a response from the 

        [ResumeSubscription](api-endpoint:Subscriptions-ResumeSubscription)
        endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered during the request.
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: The resumed subscription.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionAction'
          description: >-
            A list of `RESUME` actions created by the request and scheduled for
            the subscription.
          x-release-status: BETA
      example:
        actions:
          - effective_date: '2023-09-01'
            id: 18ff74f4-3da4-30c5-929f-7d6fca84f115
            type: RESUME
        subscription:
          card_id: ccof:qy5x8hHGYsgLrp4Q4GB
          created_at: '2023-06-20T21:53:10Z'
          customer_id: CHFGVKYY8RSV93M5KCYTG4PN0G
          id: 56214fb2-cc85-47a1-93bc-44f3766bb56f
          location_id: S8GWD5R9QB376
          phases:
            - order_template_id: U2NaowWxzXwpsZU697x7ZHOAnCNZY
              ordinal: 0
              plan_phase_uid: X2Q2AONPB3RB64Y27S25QCZP
              uid: 873451e0-745b-4e87-ab0b-c574933fe616
          plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
          source:
            name: My Application
          start_date: '2023-06-20'
          status: ACTIVE
          timezone: America/Los_Angeles
          version: 1
    RetrieveBookingCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents a
        [RetrieveBookingCustomAttributeDefinition](api-endpoint:BookingCustomAttributes-RetrieveBookingCustomAttributeDefinition)
        request.
      x-release-status: PUBLIC
      properties:
        version:
          type: integer
          description: >-
            The current version of the custom attribute definition, which is
            used for strongly consistent

            reads to guarantee that you receive the most up-to-date data. When
            included in the request,

            Square returns the specified version or a higher version if one
            exists. If the specified version

            is higher than the current version, Square returns a `BAD_REQUEST`
            error.
    RetrieveBookingCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a
        [RetrieveBookingCustomAttributeDefinition](api-endpoint:BookingCustomAttributes-RetrieveBookingCustomAttributeDefinition)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: PUBLIC
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The retrieved custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2022-11-16T15:27:30Z'
          description: The favorite shampoo of the customer.
          key: favoriteShampoo
          name: Favorite shampoo
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          updated_at: '2022-11-16T15:27:30Z'
          version: 1
          visibility: VISIBILITY_READ_WRITE_VALUES
        errors: []
    RetrieveBookingCustomAttributeRequest:
      type: object
      description: >-
        Represents a
        [RetrieveBookingCustomAttribute](api-endpoint:BookingCustomAttributes-RetrieveBookingCustomAttribute)
        request.
      x-release-status: PUBLIC
      properties:
        with_definition:
          type: boolean
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of

            the custom attribute. Set this parameter to `true` to get the name
            and description of the custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          nullable: true
        version:
          type: integer
          description: >-
            The current version of the custom attribute, which is used for
            strongly consistent reads to

            guarantee that you receive the most up-to-date data. When included
            in the request, Square

            returns the specified version or a higher version if one exists. If
            the specified version is

            higher than the current version, Square returns a `BAD_REQUEST`
            error.
    RetrieveBookingCustomAttributeResponse:
      type: object
      description: >-
        Represents a
        [RetrieveBookingCustomAttribute](api-endpoint:BookingCustomAttributes-RetrieveBookingCustomAttribute)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: PUBLIC
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The retrieved custom attribute. If `with_definition` was set to
            `true` in the request,

            the custom attribute definition is returned in the `definition`
            field.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute:
          created_at: '2022-11-16T15:50:27Z'
          key: favoriteShampoo
          updated_at: '2022-11-16T15:50:27Z'
          value: Dune
          version: 1
          visibility: VISIBILITY_READ_ONLY
        errors: []
    RetrieveBookingRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
    RetrieveBookingResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        booking:
          $ref: '#/components/schemas/Booking'
          description: The booking that was requested.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
      example:
        booking:
          appointment_segments:
            - duration_minutes: 60
              service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
              service_variation_version: 1599775456731
              team_member_id: TMXUrsBWWcHTt79t
          created_at: '2020-10-28T15:47:41Z'
          customer_id: EX2QSVGTZN4K1E5QE1CBFNVQ8M
          customer_note: ''
          id: zkras0xv0xwswx
          location_id: LEQHH0YY8B42M
          seller_note: ''
          start_at: '2020-11-26T13:00:00Z'
          status: ACCEPTED
          updated_at: '2020-10-28T15:49:25Z'
          version: 1
        errors: []
    RetrieveBusinessBookingProfileRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
    RetrieveBusinessBookingProfileResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        business_booking_profile:
          $ref: '#/components/schemas/BusinessBookingProfile'
          description: The seller's booking profile.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
      example:
        business_booking_profile:
          allow_user_cancel: true
          booking_enabled: true
          booking_policy: ACCEPT_ALL
          business_appointment_settings:
            alignment_time: HALF_HOURLY
            any_team_member_booking_enabled: true
            cancellation_fee_money:
              currency: USD
            cancellation_policy: CUSTOM_POLICY
            location_types:
              - BUSINESS_LOCATION
            max_booking_lead_time_seconds: 31536000
            min_booking_lead_time_seconds: 0
            multiple_service_booking_enabled: true
            skip_booking_flow_staff_selection: false
          created_at: '2020-09-10T21:40:38Z'
          customer_timezone_choice: CUSTOMER_CHOICE
          seller_id: MLJQYZZRM0D3Y
        errors: []
    RetrieveCardRequest:
      type: object
      description: |-
        Retrieves details for a specific Card. Accessible via
        HTTP requests at GET https://connect.squareup.com/v2/cards/{card_id}
      x-release-status: PUBLIC
      properties: {}
      example: {}
    RetrieveCardResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [RetrieveCard](api-endpoint:Cards-RetrieveCard)
        endpoint.


        Note: if there are errors processing the request, the card field will
        not be

        present.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        card:
          $ref: '#/components/schemas/Card'
          description: The retrieved card.
      example:
        card:
          billing_address:
            address_line_1: 500 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          bin: '411111'
          card_brand: VISA
          card_type: CREDIT
          cardholder_name: Amelia Earhart
          customer_id: VDKXEEKPJN48QDG3BGGFAK05P8
          enabled: true
          exp_month: 11
          exp_year: 2022
          fingerprint: >-
            ex-p-cs80EK9Flz7LsCMv-szbptQ_ssAGrhemzSTsPFgt9nzyE6t7okiLIQc-qw_quqKX4Q
          id: ccof:uIbfJXhXETSP197M3GB
          last_4: '1111'
          merchant_id: 6SSW7HV8K2ST5
          prepaid_type: NOT_PREPAID
          reference_id: user-id-1
          version: 1
    RetrieveCashDrawerShiftRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - location_id
      properties:
        location_id:
          type: string
          description: The ID of the location to retrieve cash drawer shifts from.
          minLength: 1
      example: {}
    RetrieveCashDrawerShiftResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        cash_drawer_shift:
          $ref: '#/components/schemas/CashDrawerShift'
          description: The cash drawer shift queried for.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        cash_drawer_shift:
          cash_paid_in_money:
            amount: 10000
            currency: USD
          cash_paid_out_money:
            amount: -10000
            currency: USD
          cash_payment_money:
            amount: 100
            currency: USD
          cash_refunds_money:
            amount: -100
            currency: USD
          closed_at: '2019-11-22T00:44:49.000Z'
          closed_cash_money:
            amount: 9970
            currency: USD
          closing_team_member_id: ''
          description: Misplaced some change
          device:
            name: My iPad
          ended_at: '2019-11-22T00:44:49.000Z'
          ending_team_member_id: ''
          expected_cash_money:
            amount: 10000
            currency: USD
          id: DCC99978-09A6-4926-849F-300BE9C5793A
          opened_at: '2019-11-22T00:42:54.000Z'
          opened_cash_money:
            amount: 10000
            currency: USD
          opening_team_member_id: ''
          state: CLOSED
    RetrieveCatalogObjectRequest:
      type: object
      x-release-status: PUBLIC
      x-params-example: '?include_related_objects=true'
      properties:
        include_related_objects:
          type: boolean
          description: >-
            If `true`, the response will include additional objects that are
            related to the

            requested objects. Related objects are defined as any objects
            referenced by ID by the results in the `objects` field

            of the response. These objects are put in the `related_objects`
            field. Setting this to `true` is

            helpful when the objects are needed for immediate display to a user.

            This process only goes one level deep. Objects referenced by the
            related objects will not be included. For example,


            if the `objects` field of the response contains a CatalogItem, its
            associated

            CatalogCategory objects, CatalogTax objects, CatalogImage objects
            and

            CatalogModifierLists will be returned in the `related_objects` field
            of the

            response. If the `objects` field of the response contains a
            CatalogItemVariation,

            its parent CatalogItem will be returned in the `related_objects`
            field of

            the response.


            Default value: `false`
          nullable: true
        catalog_version:
          type: integer
          description: >-
            Requests objects as of a specific version of the catalog. This
            allows you to retrieve historical

            versions of objects. The value to retrieve a specific version of an
            object can be found

            in the version field of [CatalogObject](entity:CatalogObject)s. If
            not included, results will

            be from the current version of the catalog.
          format: int64
          x-release-status: BETA
          nullable: true
        include_category_path_to_root:
          type: boolean
          description: >-
            Specifies whether or not to include the `path_to_root` list for each
            returned category instance. The `path_to_root` list consists

            of `CategoryPathToRootNode` objects and specifies the path that
            starts with the immediate parent category of the returned category

            and ends with its root category. If the returned category is a
            top-level category, the `path_to_root` list is empty and is not
            returned

            in the response payload.
          nullable: true
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/RetrieveCatalogObject/RetrieveCatalogObjectRequest.csharp
        java: >-
          /sdk_samples/Catalog/RetrieveCatalogObject/RetrieveCatalogObjectRequest.java
        javascript: >-
          /sdk_samples/Catalog/RetrieveCatalogObject/RetrieveCatalogObjectRequest.javascript
        php: >-
          /sdk_samples/Catalog/RetrieveCatalogObject/RetrieveCatalogObjectRequest.php
        python: >-
          /sdk_samples/Catalog/RetrieveCatalogObject/RetrieveCatalogObjectRequest.python
        ruby: >-
          /sdk_samples/Catalog/RetrieveCatalogObject/RetrieveCatalogObjectRequest.ruby
    RetrieveCatalogObjectResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        object:
          $ref: '#/components/schemas/CatalogObject'
          description: The `CatalogObject`s returned.
        related_objects:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: >-
            A list of `CatalogObject`s referenced by the object in the `object`
            field.
      example:
        object:
          id: W62UWFY35CWMYGVWK6TWJDNI
          is_deleted: false
          item_data:
            categories:
              - id: BJNQCF2FJ6S6UIDT65ABHLRX
                ordinal: 0
            description: Hot Leaf Juice
            name: Tea
            tax_ids:
              - HURXQOOAIC4IZSI2BEXQRYFY
            variations:
              - id: 2TZFAOHWGG7PAK2QEXWYPZSP
                is_deleted: false
                item_variation_data:
                  item_id: W62UWFY35CWMYGVWK6TWJDNI
                  name: Mug
                  ordinal: 0
                  price_money:
                    amount: 150
                    currency: USD
                  pricing_type: FIXED_PRICING
                present_at_all_locations: true
                type: ITEM_VARIATION
                updated_at: '2016-11-16T22:25:24.878Z'
                version: 1479335124878
          present_at_all_locations: true
          type: ITEM
          updated_at: '2016-11-16T22:25:24.878Z'
          version: 1479335124878
        related_objects:
          - category_data:
              name: Beverages
            id: BJNQCF2FJ6S6UIDT65ABHLRX
            is_deleted: false
            present_at_all_locations: true
            type: CATEGORY
            updated_at: '2016-11-16T22:25:24.878Z'
            version: 1479335124878
          - id: HURXQOOAIC4IZSI2BEXQRYFY
            is_deleted: false
            present_at_all_locations: true
            tax_data:
              calculation_phase: TAX_SUBTOTAL_PHASE
              enabled: true
              inclusion_type: ADDITIVE
              name: Sales Tax
              percentage: '5.0'
            type: TAX
            updated_at: '2016-11-16T22:25:24.878Z'
            version: 1479335124878
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/RetrieveCatalogObject/RetrieveCatalogObjectResponse.csharp
        java: >-
          /sdk_samples/Catalog/RetrieveCatalogObject/RetrieveCatalogObjectResponse.java
        javascript: >-
          /sdk_samples/Catalog/RetrieveCatalogObject/RetrieveCatalogObjectResponse.javascript
        php: >-
          /sdk_samples/Catalog/RetrieveCatalogObject/RetrieveCatalogObjectResponse.php
        python: >-
          /sdk_samples/Catalog/RetrieveCatalogObject/RetrieveCatalogObjectResponse.python
        ruby: >-
          /sdk_samples/Catalog/RetrieveCatalogObject/RetrieveCatalogObjectResponse.ruby
    RetrieveCustomerCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents a
        [RetrieveCustomerCustomAttributeDefinition](api-endpoint:CustomerCustomAttributes-RetrieveCustomerCustomAttributeDefinition)
        request.
      x-release-status: PUBLIC
      x-params-example: '?key=favoritemovie'
      properties:
        version:
          type: integer
          description: >-
            The current version of the custom attribute definition, which is
            used for strongly consistent

            reads to guarantee that you receive the most up-to-date data. When
            included in the request,

            Square returns the specified version or a higher version if one
            exists. If the specified version

            is higher than the current version, Square returns a `BAD_REQUEST`
            error.
    RetrieveCustomerCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a
        [RetrieveCustomerCustomAttributeDefinition](api-endpoint:CustomerCustomAttributes-RetrieveCustomerCustomAttributeDefinition)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: PUBLIC
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The retrieved custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2022-04-26T15:27:30Z'
          description: The favorite movie of the customer.
          key: favoritemovie
          name: Favorite Movie
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          updated_at: '2022-04-26T15:27:30Z'
          version: 1
          visibility: VISIBILITY_READ_WRITE_VALUES
    RetrieveCustomerCustomAttributeRequest:
      type: object
      description: >-
        Represents a
        [RetrieveCustomerCustomAttribute](api-endpoint:CustomerCustomAttributes-RetrieveCustomerCustomAttribute)
        request.
      x-release-status: PUBLIC
      x-params-example: '?customer_id=Z57QXKM2FGXEQDV42W8RBZY7BR&key=favoritemovie'
      properties:
        with_definition:
          type: boolean
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of

            the custom attribute. Set this parameter to `true` to get the name
            and description of the custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          nullable: true
        version:
          type: integer
          description: >-
            The current version of the custom attribute, which is used for
            strongly consistent reads to

            guarantee that you receive the most up-to-date data. When included
            in the request, Square

            returns the specified version or a higher version if one exists. If
            the specified version is

            higher than the current version, Square returns a `BAD_REQUEST`
            error.
    RetrieveCustomerCustomAttributeResponse:
      type: object
      description: >-
        Represents a
        [RetrieveCustomerCustomAttribute](api-endpoint:CustomerCustomAttributes-RetrieveCustomerCustomAttribute)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: PUBLIC
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The retrieved custom attribute. If `with_definition` was set to
            `true` in the request,

            the custom attribute definition is returned in the `definition`
            field.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute:
          created_at: '2022-04-26T15:50:27Z'
          key: favoritemovie
          updated_at: '2022-04-26T15:50:27Z'
          value: Dune
          version: 1
          visibility: VISIBILITY_READ_ONLY
    RetrieveCustomerGroupRequest:
      type: object
      description: >-
        Defines the fields that can be included in a request to the

        [RetrieveCustomerGroup](api-endpoint:CustomerGroups-RetrieveCustomerGroup)
        endpoint.
      x-release-status: PUBLIC
      properties: {}
      example: {}
    RetrieveCustomerGroupResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [RetrieveCustomerGroup](api-endpoint:CustomerGroups-RetrieveCustomerGroup)
        endpoint.


        Either `errors` or `group` is present in a given response (never both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        group:
          $ref: '#/components/schemas/CustomerGroup'
          description: The retrieved customer group.
      example:
        group:
          created_at: '2020-04-13T21:54:57.863Z'
          id: 2TAT3CMH4Q0A9M87XJZED0WMR3
          name: Loyal Customers
          updated_at: '2020-04-13T21:54:58Z'
    RetrieveCustomerRequest:
      type: object
      description: >-
        Defines the fields that are included in requests to the
        `RetrieveCustomer`

        endpoint.
      x-release-status: PUBLIC
      properties: {}
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/RetrieveCustomer/RetrieveCustomerRequest.csharp
        java: /sdk_samples/RetrieveCustomer/RetrieveCustomerRequest.java
        javascript: /sdk_samples/RetrieveCustomer/RetrieveCustomerRequest.javascript
        php: /sdk_samples/RetrieveCustomer/RetrieveCustomerRequest.php
        python: /sdk_samples/RetrieveCustomer/RetrieveCustomerRequest.python
        ruby: /sdk_samples/RetrieveCustomer/RetrieveCustomerRequest.ruby
    RetrieveCustomerResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the `RetrieveCustomer` endpoint.


        Either `errors` or `customer` is present in a given response (never
        both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        customer:
          $ref: '#/components/schemas/Customer'
          description: The requested customer.
      example:
        customer:
          address:
            address_line_1: 500 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          created_at: '2016-03-23T20:21:54.859Z'
          creation_source: THIRD_PARTY
          email_address: Amelia.Earhart@example.com
          family_name: Earhart
          given_name: Amelia
          group_ids:
            - 545AXB44B4XXWMVQ4W8SBT3HHF
          id: JDKYHBWT1D4F8MFH63DBMEN8Y4
          note: a customer
          phone_number: +1-212-555-4240
          preferences:
            email_unsubscribed: false
          reference_id: YOUR_REFERENCE_ID
          segment_ids:
            - 1KB9JE5EGJXCW.REACHABLE
          updated_at: '2016-03-23T20:21:54.859Z'
          version: 1
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/RetrieveCustomer/RetrieveCustomerResponse.csharp
        java: /sdk_samples/RetrieveCustomer/RetrieveCustomerResponse.java
        javascript: /sdk_samples/RetrieveCustomer/RetrieveCustomerResponse.javascript
        php: /sdk_samples/RetrieveCustomer/RetrieveCustomerResponse.php
        python: /sdk_samples/RetrieveCustomer/RetrieveCustomerResponse.python
        ruby: /sdk_samples/RetrieveCustomer/RetrieveCustomerResponse.ruby
    RetrieveCustomerSegmentRequest:
      type: object
      description: >-
        Defines the valid parameters for requests to the
        `RetrieveCustomerSegmentRequest` endpoint.
      x-release-status: PUBLIC
      properties: {}
      example: {}
    RetrieveCustomerSegmentResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body for requests
        to the `RetrieveCustomerSegment` endpoint.


        Either `errors` or `segment` is present in a given response (never
        both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        segment:
          $ref: '#/components/schemas/CustomerSegment'
          description: The retrieved customer segment.
      example:
        segment:
          created_at: '2020-01-09T19:33:24.469Z'
          id: GMNXRZVEXNQDF.CHURN_RISK
          name: Lapsed
          updated_at: '2020-04-13T23:01:13Z'
    RetrieveDisputeEvidenceRequest:
      type: object
      description: Defines the parameters for a `RetrieveDisputeEvidence` request.
      x-release-status: PUBLIC
      properties: {}
      example: {}
    RetrieveDisputeEvidenceResponse:
      type: object
      description: Defines the fields in a `RetrieveDisputeEvidence` response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        evidence:
          $ref: '#/components/schemas/DisputeEvidence'
          description: Metadata about the dispute evidence file.
      example:
        evidence:
          dispute_id: bVTprrwk0gygTLZ96VX1oB
          evidence_file:
            filename: customer-interaction.jpg
            filetype: image/jpeg
          evidence_type: CARDHOLDER_COMMUNICATION
          id: TOomLInj6iWmP3N8qfCXrB
          uploaded_at: '2022-05-18T16:01:10.000Z'
    RetrieveDisputeRequest:
      type: object
      description: Defines the request parameters for the `RetrieveDispute` endpoint.
      x-release-status: PUBLIC
      properties: {}
      example: {}
    RetrieveDisputeResponse:
      type: object
      description: Defines fields in a `RetrieveDispute` response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        dispute:
          $ref: '#/components/schemas/Dispute'
          description: Details about the requested `Dispute`.
      example:
        dispute:
          amount_money:
            amount: 2500
            currency: USD
          brand_dispute_id: '100000809947'
          card_brand: VISA
          created_at: '2022-06-29T18:45:22.265Z'
          disputed_payment:
            payment_id: zhyh1ch64kRBrrlfVhwjCEjZWzNZY
          due_at: '2022-07-13T00:00:00.000Z'
          id: XDgyFu7yo1E2S5lQGGpYn
          location_id: L1HN3ZMQK64X9
          reason: NO_KNOWLEDGE
          reported_at: '2022-06-29T00:00:00.000Z'
          state: ACCEPTED
          updated_at: '2022-07-07T19:14:42.650Z'
          version: 2
    RetrieveEmployeeRequest:
      type: object
      x-release-status: DEPRECATED
      properties: {}
    RetrieveEmployeeResponse:
      type: object
      x-release-status: DEPRECATED
      properties:
        employee:
          $ref: '#/components/schemas/Employee'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
    RetrieveGiftCardFromGANRequest:
      type: object
      description: A request to retrieve gift cards by their GANs.
      x-release-status: PUBLIC
      required:
        - gan
      properties:
        gan:
          type: string
          description: >-
            The gift card account number (GAN) of the gift card to retrieve.

            The maximum length of a GAN is 255 digits to account for third-party
            GANs that have been imported.

            Square-issued gift cards have 16-digit GANs.
          minLength: 1
          maxLength: 255
      example:
        gan: '7783320001001635'
    RetrieveGiftCardFromGANResponse:
      type: object
      description: >-
        A response that contains a `GiftCard`. This response might contain a set
        of `Error` objects

        if the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        gift_card:
          $ref: '#/components/schemas/GiftCard'
          description: >-
            A gift card that was fetched, if present. It returns empty if an
            error occurred.
      example:
        gift_card:
          balance_money:
            amount: 5000
            currency: USD
          created_at: '2021-05-20T22:26:54.000Z'
          gan: '7783320001001635'
          gan_source: SQUARE
          id: gftc:6944163553804e439d89adb47caf806a
          state: ACTIVE
          type: DIGITAL
    RetrieveGiftCardFromNonceRequest:
      type: object
      description: A request to retrieve a gift card by using a payment token.
      x-release-status: PUBLIC
      required:
        - nonce
      properties:
        nonce:
          type: string
          description: >-
            The payment token of the gift card to retrieve. Payment tokens are
            generated by the 

            Web Payments SDK or In-App Payments SDK.
          minLength: 1
      example:
        nonce: cnon:7783322135245171
    RetrieveGiftCardFromNonceResponse:
      type: object
      description: >-
        A response that contains a `GiftCard` object. If the request resulted in
        errors, 

        the response contains a set of `Error` objects.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        gift_card:
          $ref: '#/components/schemas/GiftCard'
          description: The retrieved gift card.
      example:
        gift_card:
          balance_money:
            amount: 5000
            currency: USD
          created_at: '2021-05-20T22:26:54.000Z'
          gan: '7783320001001635'
          gan_source: SQUARE
          id: gftc:6944163553804e439d89adb47caf806a
          state: ACTIVE
          type: DIGITAL
    RetrieveGiftCardRequest:
      type: object
      description: A request to retrieve digital gift cards.
      x-release-status: PUBLIC
      x-params-example: '?id=gftc:00113070ba5745f0b2377c1b9570cb03'
      properties: {}
    RetrieveGiftCardResponse:
      type: object
      description: >-
        A response that contains a `GiftCard`. The response might contain a set
        of `Error` objects

        if the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        gift_card:
          $ref: '#/components/schemas/GiftCard'
          description: The gift card retrieved.
      example:
        gift_card:
          balance_money:
            amount: 1000
            currency: USD
          created_at: '2021-05-20T22:26:54.000Z'
          gan: '7783320001001635'
          gan_source: SQUARE
          id: gftc:00113070ba5745f0b2377c1b9570cb03
          state: ACTIVE
          type: DIGITAL
    RetrieveInventoryAdjustmentRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Inventory/RetrieveInventoryAdjustment/RetrieveInventoryAdjustmentRequest.csharp
        java: >-
          /sdk_samples/Inventory/RetrieveInventoryAdjustment/RetrieveInventoryAdjustmentRequest.java
        javascript: >-
          /sdk_samples/Inventory/RetrieveInventoryAdjustment/RetrieveInventoryAdjustmentRequest.javascript
        php: >-
          /sdk_samples/Inventory/RetrieveInventoryAdjustment/RetrieveInventoryAdjustmentRequest.php
        python: >-
          /sdk_samples/Inventory/RetrieveInventoryAdjustment/RetrieveInventoryAdjustmentRequest.python
        ruby: >-
          /sdk_samples/Inventory/RetrieveInventoryAdjustment/RetrieveInventoryAdjustmentRequest.ruby
    RetrieveInventoryAdjustmentResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        adjustment:
          $ref: '#/components/schemas/InventoryAdjustment'
          description: The requested [InventoryAdjustment](entity:InventoryAdjustment).
      example:
        adjustment:
          catalog_object_id: W62UWFY35CWMYGVWK6TWJDNI
          catalog_object_type: ITEM_VARIATION
          created_at: '2016-11-17T13:02:15.142Z'
          from_state: IN_STOCK
          id: UDMOEO78BG6GYWA2XDRYX3KB
          location_id: C6W5YS5QM06F5
          occurred_at: '2016-11-16T25:44:22.837Z'
          quantity: '7'
          reference_id: 4a366069-4096-47a2-99a5-0084ac879509
          source:
            application_id: 416ff29c-86c4-4feb-b58c-9705f21f3ea0
            name: Square Point of Sale 4.37
            product: SQUARE_POS
          team_member_id: LRK57NSQ5X7PUD05
          to_state: SOLD
          total_price_money:
            amount: 4550
            currency: USD
        errors: []
    RetrieveInventoryChangesRequest:
      type: object
      x-release-status: PUBLIC
      x-params-example: '?location_ids=&cursor='
      properties:
        location_ids:
          type: string
          description: |-
            The [Location](entity:Location) IDs to look up as a comma-separated
            list. An empty list queries all locations.
          nullable: true
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for the original
            query.


            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
          nullable: true
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Inventory/RetrieveInventoryChanges/RetrieveInventoryChangesRequest.csharp
        java: >-
          /sdk_samples/Inventory/RetrieveInventoryChanges/RetrieveInventoryChangesRequest.java
        javascript: >-
          /sdk_samples/Inventory/RetrieveInventoryChanges/RetrieveInventoryChangesRequest.javascript
        php: >-
          /sdk_samples/Inventory/RetrieveInventoryChanges/RetrieveInventoryChangesRequest.php
        python: >-
          /sdk_samples/Inventory/RetrieveInventoryChanges/RetrieveInventoryChangesRequest.python
        ruby: >-
          /sdk_samples/Inventory/RetrieveInventoryChanges/RetrieveInventoryChangesRequest.ruby
    RetrieveInventoryChangesResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        changes:
          type: array
          items:
            $ref: '#/components/schemas/InventoryChange'
          description: The set of inventory changes for the requested object and locations.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If unset,

            this is the final response.


            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
      example:
        changes:
          - adjustment:
              catalog_object_id: W62UWFY35CWMYGVWK6TWJDNI
              catalog_object_type: ITEM_VARIATION
              created_at: '2016-11-16T22:25:24.878Z'
              from_state: IN_STOCK
              id: OJKJIUANKLMLQANZADNPLKAD
              location_id: C6W5YS5QM06F5
              occurred_at: '2016-11-16T22:25:24.878Z'
              quantity: '3'
              reference_id: d8207693-168f-4b44-a2fd-a7ff533ddd26
              source:
                application_id: 416ff29c-86c4-4feb-b58c-9705f21f3ea0
                name: Square Point of Sale 4.37
                product: SQUARE_POS
              team_member_id: AV7YRCGI2H1J5NQ8E1XIZCNA
              to_state: SOLD
              total_price_money:
                amount: 5000
                currency: USD
              transaction_id: 5APV6JYK1SNCZD11AND2RX1Z
            type: ADJUSTMENT
        errors: []
    RetrieveInventoryCountRequest:
      type: object
      x-release-status: PUBLIC
      x-params-example: '?location_ids=C6W5YS5QM06F5&cursor='
      properties:
        location_ids:
          type: string
          description: |-
            The [Location](entity:Location) IDs to look up as a comma-separated
            list. An empty list queries all locations.
          nullable: true
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for the original
            query.


            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
          nullable: true
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Inventory/RetrieveInventoryCount/RetrieveInventoryCountRequest.csharp
        java: >-
          /sdk_samples/Inventory/RetrieveInventoryCount/RetrieveInventoryCountRequest.java
        javascript: >-
          /sdk_samples/Inventory/RetrieveInventoryCount/RetrieveInventoryCountRequest.javascript
        php: >-
          /sdk_samples/Inventory/RetrieveInventoryCount/RetrieveInventoryCountRequest.php
        python: >-
          /sdk_samples/Inventory/RetrieveInventoryCount/RetrieveInventoryCountRequest.python
        ruby: >-
          /sdk_samples/Inventory/RetrieveInventoryCount/RetrieveInventoryCountRequest.ruby
    RetrieveInventoryCountResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        counts:
          type: array
          items:
            $ref: '#/components/schemas/InventoryCount'
          description: |-
            The current calculated inventory counts for the requested object and
            locations.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If unset,

            this is the final response.


            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
      example:
        counts:
          - calculated_at: '2016-11-16T22:28:01.223Z'
            catalog_object_id: W62UWFY35CWMYGVWK6TWJDNI
            catalog_object_type: ITEM_VARIATION
            location_id: C6W5YS5QM06F5
            quantity: '22'
            state: IN_STOCK
        errors: []
    RetrieveInventoryPhysicalCountRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Inventory/RetrieveInventoryPhysicalCount/RetrieveInventoryPhysicalCountRequest.csharp
        java: >-
          /sdk_samples/Inventory/RetrieveInventoryPhysicalCount/RetrieveInventoryPhysicalCountRequest.java
        javascript: >-
          /sdk_samples/Inventory/RetrieveInventoryPhysicalCount/RetrieveInventoryPhysicalCountRequest.javascript
        php: >-
          /sdk_samples/Inventory/RetrieveInventoryPhysicalCount/RetrieveInventoryPhysicalCountRequest.php
        python: >-
          /sdk_samples/Inventory/RetrieveInventoryPhysicalCount/RetrieveInventoryPhysicalCountRequest.python
        ruby: >-
          /sdk_samples/Inventory/RetrieveInventoryPhysicalCount/RetrieveInventoryPhysicalCountRequest.ruby
    RetrieveInventoryPhysicalCountResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        count:
          $ref: '#/components/schemas/InventoryPhysicalCount'
          description: >-
            The requested
            [InventoryPhysicalCount](entity:InventoryPhysicalCount).
      example:
        count:
          catalog_object_id: W62UWFY35CWMYGVWK6TWJDNI
          catalog_object_type: ITEM_VARIATION
          created_at: '2016-11-16T22:25:24.878Z'
          id: ANZADNPLKADOJKJIUANKLMLQ
          location_id: C6W5YS5QM06F5
          occurred_at: '2016-11-16T22:25:24.878Z'
          quantity: '15'
          reference_id: f857ec37-f9a0-4458-8e23-5b5e0bea4e53
          source:
            application_id: 416ff29c-86c4-4feb-b58c-9705f21f3ea0
            name: Square Point of Sale 4.37
            product: SQUARE_POS
          state: IN_STOCK
          team_member_id: LRK57NSQ5X7PUD05
        errors: []
    RetrieveInventoryTransferRequest:
      type: object
      x-release-status: BETA
      properties: {}
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Inventory/RetrieveInventoryTransfer/RetrieveInventoryTransferRequest.csharp
        java: >-
          /sdk_samples/Inventory/RetrieveInventoryTransfer/RetrieveInventoryTransferRequest.java
        javascript: >-
          /sdk_samples/Inventory/RetrieveInventoryTransfer/RetrieveInventoryTransferRequest.javascript
        php: >-
          /sdk_samples/Inventory/RetrieveInventoryTransfer/RetrieveInventoryTransferRequest.php
        python: >-
          /sdk_samples/Inventory/RetrieveInventoryTransfer/RetrieveInventoryTransferRequest.python
        ruby: >-
          /sdk_samples/Inventory/RetrieveInventoryTransfer/RetrieveInventoryTransferRequest.ruby
    RetrieveInventoryTransferResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        transfer:
          $ref: '#/components/schemas/InventoryTransfer'
          description: The requested [InventoryTransfer](entity:InventoryTransfer).
      example:
        errors: []
        transfer:
          catalog_object_id: W62UWFY35CWMYGVWK6TWJDNI
          catalog_object_type: ITEM_VARIATION
          created_at: '2016-11-17T13:02:15.142Z'
          from_location_id: C6W5YS5QM06F5
          id: UDMOEO78BG6GYWA2XDRYX3KB
          occurred_at: '2016-11-16T25:44:22.837Z'
          quantity: '7'
          reference_id: 4a366069-4096-47a2-99a5-0084ac879509
          source:
            application_id: 416ff29c-86c4-4feb-b58c-9705f21f3ea0
            name: Square Point of Sale 4.37
            product: SQUARE_POS
          state: IN_STOCK
          team_member_id: LRK57NSQ5X7PUD05
          to_location_id: 59TNP9SA8VGDA
    RetrieveJobRequest:
      type: object
      description: Represents a [RetrieveJob](api-endpoint:Team-RetrieveJob) request.
      x-release-status: BETA
      properties: {}
      example: {}
    RetrieveJobResponse:
      type: object
      description: >-
        Represents a [RetrieveJob](api-endpoint:Team-RetrieveJob) response.
        Either `job` or `errors`

        is present in the response.
      x-release-status: BETA
      properties:
        job:
          $ref: '#/components/schemas/Job'
          description: The retrieved job.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: The errors that occurred during the request.
      example:
        job:
          created_at: '2021-06-11T22:55:45Z'
          id: 1yJlHapkseYnNPETIU1B
          is_tip_eligible: true
          title: Cashier 1
          updated_at: '2021-06-11T22:55:45Z'
          version: 2
    RetrieveLocationBookingProfileRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
    RetrieveLocationBookingProfileResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        location_booking_profile:
          $ref: '#/components/schemas/LocationBookingProfile'
          description: The requested location booking profile.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
      example:
        errors: []
        location_booking_profile:
          booking_enabled: true
          booking_site_url: https://square.site/book/L3HETDGYQ4A2C/prod-business
          location_id: L3HETDGYQ4A2C
    RetrieveLocationCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents a
        [RetrieveLocationCustomAttributeDefinition](api-endpoint:LocationCustomAttributes-RetrieveLocationCustomAttributeDefinition)
        request.
      x-release-status: BETA
      x-params-example: '?key=bestseller'
      properties:
        version:
          type: integer
          description: >-
            The current version of the custom attribute definition, which is
            used for strongly consistent

            reads to guarantee that you receive the most up-to-date data. When
            included in the request,

            Square returns the specified version or a higher version if one
            exists. If the specified version

            is higher than the current version, Square returns a `BAD_REQUEST`
            error.
    RetrieveLocationCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a
        [RetrieveLocationCustomAttributeDefinition](api-endpoint:LocationCustomAttributes-RetrieveLocationCustomAttributeDefinition)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: BETA
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The retrieved custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2022-12-02T19:06:36.559Z'
          description: Bestselling item at location
          key: bestseller
          name: Bestseller
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          updated_at: '2022-12-02T19:06:36.559Z'
          version: 1
          visibility: VISIBILITY_READ_WRITE_VALUES
    RetrieveLocationCustomAttributeRequest:
      type: object
      description: >-
        Represents a
        [RetrieveLocationCustomAttribute](api-endpoint:LocationCustomAttributes-RetrieveLocationCustomAttribute)
        request.
      x-release-status: BETA
      x-params-example: '?location_id=L0TBCBTB7P8RQ&key=bestseller'
      properties:
        with_definition:
          type: boolean
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of

            the custom attribute. Set this parameter to `true` to get the name
            and description of the custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          nullable: true
        version:
          type: integer
          description: >-
            The current version of the custom attribute, which is used for
            strongly consistent reads to

            guarantee that you receive the most up-to-date data. When included
            in the request, Square

            returns the specified version or a higher version if one exists. If
            the specified version is

            higher than the current version, Square returns a `BAD_REQUEST`
            error.
    RetrieveLocationCustomAttributeResponse:
      type: object
      description: >-
        Represents a
        [RetrieveLocationCustomAttribute](api-endpoint:LocationCustomAttributes-RetrieveLocationCustomAttribute)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: BETA
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The retrieved custom attribute. If `with_definition` was set to
            `true` in the request,

            the custom attribute definition is returned in the `definition`
            field.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute:
          created_at: '2023-01-09T19:02:58.647Z'
          key: bestseller
          updated_at: '2023-01-09T19:21:04.551Z'
          value: hot cocoa
          version: 2
          visibility: VISIBILITY_READ_WRITE_VALUES
    RetrieveLocationRequest:
      type: object
      description: |-
        Defines the fields that are included in the request body for the
        [RetrieveLocation](api-endpoint:Locations-RetrieveLocation) endpoint.
      x-release-status: PUBLIC
      properties: {}
    RetrieveLocationResponse:
      type: object
      description: >-
        Defines the fields that the
        [RetrieveLocation](api-endpoint:Locations-RetrieveLocation)

        endpoint returns in a response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        location:
          $ref: '#/components/schemas/Location'
          description: The requested location.
      example:
        location:
          address:
            address_line_1: 123 Main St
            administrative_district_level_1: CA
            country: US
            locality: San Francisco
            postal_code: '94114'
          business_name: Jet Fuel Coffee
          capabilities:
            - CREDIT_CARD_PROCESSING
          country: US
          created_at: '2016-09-19T17:33:12Z'
          currency: USD
          id: 18YC4JDH91E1H
          language_code: en-US
          merchant_id: 3MYCJG5GVYQ8Q
          name: Grant Park
          phone_number: +1 650-354-7217
          status: ACTIVE
          timezone: America/Los_Angeles
    RetrieveLocationSettingsRequest:
      type: object
      x-release-status: BETA
      properties: {}
    RetrieveLocationSettingsResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        location_settings:
          $ref: '#/components/schemas/CheckoutLocationSettings'
          description: The location settings.
      example:
        location_settings:
          branding:
            button_color: '#ffffff'
            button_shape: ROUNDED
            header_type: FRAMED_LOGO
          customer_notes_enabled: true
          location_id: LOCATION_ID_1
          policies:
            - description: This is my Return Policy
              title: Return Policy
              uid: POLICY_ID_1
          tipping:
            default_percent: 15
            default_whole_amount_money:
              amount: 100
              currency: USD
            percentages:
              - 10
              - 15
              - 20
            smart_tipping_enabled: true
            whole_amounts:
              - amount: 1000
                currency: USD
              - amount: 1500
                currency: USD
              - amount: 2000
                currency: USD
          updated_at: '2022-06-16T22:25:35Z'
    RetrieveLoyaltyAccountRequest:
      type: object
      description: A request to retrieve a loyalty account.
      x-release-status: PUBLIC
      x-params-example: '?account_id=79b807d2-d786-46a9-933b-918028d7a8c5'
      properties: {}
    RetrieveLoyaltyAccountResponse:
      type: object
      description: A response that includes the loyalty account.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        loyalty_account:
          $ref: '#/components/schemas/LoyaltyAccount'
          description: The loyalty account.
      example:
        loyalty_account:
          balance: 10
          created_at: '2020-05-08T21:44:32Z'
          customer_id: Q8002FAM9V1EZ0ADB2T5609X6NET1H0
          id: 79b807d2-d786-46a9-933b-918028d7a8c5
          lifetime_points: 20
          mapping:
            created_at: '2020-05-08T21:44:32Z'
            id: 66aaab3f-da99-49ed-8b19-b87f851c844f
            phone_number: '+14155551234'
          program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
          updated_at: '2020-05-08T21:44:32Z'
    RetrieveLoyaltyProgramRequest:
      type: object
      description: >-
        A request to retrieve the [loyalty program](entity:LoyaltyProgram) that
        belongs to a seller. A seller can have only one loyalty program.
      x-release-status: PUBLIC
      x-params-example: '?program_id=main'
      properties: {}
    RetrieveLoyaltyProgramResponse:
      type: object
      description: A response that contains the loyalty program.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        program:
          $ref: '#/components/schemas/LoyaltyProgram'
          description: The loyalty program that was requested.
      example:
        program:
          accrual_rules:
            - accrual_type: SPEND
              points: 1
              spend_data:
                amount_money:
                  amount: 100
                  currency: USD
                excluded_category_ids:
                  - 7ZERJKO5PVYXCVUHV2JCZ2UG
                  - FQKAOJE5C4FIMF5A2URMLW6V
                excluded_item_variation_ids:
                  - CBZXBUVVTYUBZGQO44RHMR6B
                  - EDILT24Z2NISEXDKGY6HP7XV
                tax_mode: BEFORE_TAX
          created_at: '2020-04-20T16:55:11Z'
          id: d619f755-2d17-41f3-990d-c04ecedd64dd
          location_ids:
            - P034NEENMD09F
          reward_tiers:
            - created_at: '2020-04-20T16:55:11Z'
              definition:
                discount_type: FIXED_PERCENTAGE
                percentage_discount: '10'
                scope: ORDER
              id: e1b39225-9da5-43d1-a5db-782cdd8ad94f
              name: 10% off entire sale
              points: 10
              pricing_rule_reference:
                catalog_version: '1605486402527'
                object_id: 74C4JSHESNLTB2A7ITO5HO6F
          status: ACTIVE
          terminology:
            one: Point
            other: Points
          updated_at: '2020-05-01T02:00:02Z'
    RetrieveLoyaltyPromotionRequest:
      type: object
      description: >-
        Represents a
        [RetrieveLoyaltyPromotionPromotions](api-endpoint:Loyalty-RetrieveLoyaltyPromotion)
        request.
      x-release-status: PUBLIC
      x-params-example: >-
        ?program_id=d619f755-2d17-41f3-990d-c04ecedd64dd&promotion_id=loypromo_f0f9b849-725e-378d-b810-511237e07b67
      properties: {}
      example: {}
    RetrieveLoyaltyPromotionResponse:
      type: object
      description: >-
        Represents a
        [RetrieveLoyaltyPromotionPromotions](api-endpoint:Loyalty-RetrieveLoyaltyPromotion)
        response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        loyalty_promotion:
          $ref: '#/components/schemas/LoyaltyPromotion'
          description: The retrieved loyalty promotion.
      example:
        loyalty_promotion:
          available_time:
            start_date: '2022-08-16'
            time_periods:
              - |-
                BEGIN:VEVENT
                DTSTART:20220816T160000
                DURATION:PT2H
                RRULE:FREQ=WEEKLY;BYDAY=TU
                END:VEVENT
          created_at: '2022-08-16T08:38:54Z'
          id: loypromo_f0f9b849-725e-378d-b810-511237e07b67
          incentive:
            points_multiplier_data:
              multiplier: '3.000'
              points_multiplier: 3
            type: POINTS_MULTIPLIER
          loyalty_program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
          minimum_spend_amount_money:
            amount: 2000
            currency: USD
          name: Tuesday Happy Hour Promo
          qualifying_item_variation_ids:
            - CJ3RYL56ITAKMD4VRCM7XERS
            - AT3RYLR3TUA9C34VRCB7X5RR
          status: ACTIVE
          trigger_limit:
            interval: DAY
            times: 1
          updated_at: '2022-08-16T08:38:54Z'
    RetrieveLoyaltyRewardRequest:
      type: object
      description: A request to retrieve a loyalty reward.
      x-release-status: PUBLIC
      x-params-example: '?reward_id=9f18ac21-233a-31c3-be77-b45840f5a810'
      properties: {}
    RetrieveLoyaltyRewardResponse:
      type: object
      description: A response that includes the loyalty reward.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        reward:
          $ref: '#/components/schemas/LoyaltyReward'
          description: The loyalty reward retrieved.
      example:
        reward:
          created_at: '2020-05-08T21:55:42Z'
          id: 9f18ac21-233a-31c3-be77-b45840f5a810
          loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
          points: 10
          redeemed_at: '2020-05-08T21:56:00Z'
          reward_tier_id: e1b39225-9da5-43d1-a5db-782cdd8ad94f
          status: REDEEMED
          updated_at: '2020-05-08T21:56:00Z'
    RetrieveMerchantCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents a
        [RetrieveMerchantCustomAttributeDefinition](api-endpoint:MerchantCustomAttributes-RetrieveMerchantCustomAttributeDefinition)
        request.
      x-release-status: BETA
      x-params-example: '?key=alternative_seller_name'
      properties:
        version:
          type: integer
          description: >-
            The current version of the custom attribute definition, which is
            used for strongly consistent

            reads to guarantee that you receive the most up-to-date data. When
            included in the request,

            Square returns the specified version or a higher version if one
            exists. If the specified version

            is higher than the current version, Square returns a `BAD_REQUEST`
            error.
    RetrieveMerchantCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a
        [RetrieveMerchantCustomAttributeDefinition](api-endpoint:MerchantCustomAttributes-RetrieveMerchantCustomAttributeDefinition)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: BETA
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The retrieved custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2023-05-05T19:06:36.559Z'
          description: This is the other name this merchant goes by.
          key: alternative_seller_name
          name: Alternative Merchant Name
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          updated_at: '2023-05-05T19:06:36.559Z'
          version: 1
          visibility: VISIBILITY_READ_ONLY
    RetrieveMerchantCustomAttributeRequest:
      type: object
      description: >-
        Represents a
        [RetrieveMerchantCustomAttribute](api-endpoint:MerchantCustomAttributes-RetrieveMerchantCustomAttribute)
        request.
      x-release-status: BETA
      x-params-example: '?merchant_id=DM7VKY8Q63GNP&key=alternative_seller_name'
      properties:
        with_definition:
          type: boolean
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of

            the custom attribute. Set this parameter to `true` to get the name
            and description of the custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          nullable: true
        version:
          type: integer
          description: >-
            The current version of the custom attribute, which is used for
            strongly consistent reads to

            guarantee that you receive the most up-to-date data. When included
            in the request, Square

            returns the specified version or a higher version if one exists. If
            the specified version is

            higher than the current version, Square returns a `BAD_REQUEST`
            error.
    RetrieveMerchantCustomAttributeResponse:
      type: object
      description: >-
        Represents a
        [RetrieveMerchantCustomAttribute](api-endpoint:MerchantCustomAttributes-RetrieveMerchantCustomAttribute)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: BETA
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The retrieved custom attribute. If `with_definition` was set to
            `true` in the request,

            the custom attribute definition is returned in the `definition`
            field.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute:
          created_at: '2023-05-06T19:02:58.647Z'
          key: alternative_seller_name
          updated_at: '2023-05-06T19:21:04.551Z'
          value: Ultimate Sneaker Store
          version: 2
          visibility: VISIBILITY_READ_ONLY
    RetrieveMerchantRequest:
      type: object
      description: >-
        Request object for the
        [RetrieveMerchant](api-endpoint:Merchants-RetrieveMerchant) endpoint.
      x-release-status: PUBLIC
      properties: {}
    RetrieveMerchantResponse:
      type: object
      description: >-
        The response object returned by the
        [RetrieveMerchant](api-endpoint:Merchants-RetrieveMerchant) endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        merchant:
          $ref: '#/components/schemas/Merchant'
          description: The requested `Merchant` object.
      example:
        merchant:
          business_name: Apple A Day
          country: US
          created_at: '2021-12-10T19:25:52.484Z'
          currency: USD
          id: DM7VKY8Q63GNP
          language_code: en-US
          main_location_id: 9A65CGC72ZQG1
          status: ACTIVE
    RetrieveMerchantSettingsRequest:
      type: object
      x-release-status: BETA
      properties: {}
    RetrieveMerchantSettingsResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        merchant_settings:
          $ref: '#/components/schemas/CheckoutMerchantSettings'
          description: The merchant settings.
      example:
        merchant_settings:
          merchant_id: MERCHANT_ID
          payment_methods:
            afterpay_clearpay:
              enabled: true
              item_eligibility_range:
                max:
                  amount: 10000
                  currency: USD
                min:
                  amount: 100
                  currency: USD
              order_eligibility_range:
                max:
                  amount: 10000
                  currency: USD
                min:
                  amount: 100
                  currency: USD
            apple_pay:
              enabled: true
            cash_app_pay:
              enabled: true
            google_pay:
              enabled: true
          updated_at: '2022-06-16T22:25:35Z'
    RetrieveOrderCustomAttributeDefinitionRequest:
      type: object
      description: Represents a get request for an order custom attribute definition.
      x-release-status: BETA
      properties:
        version:
          type: integer
          description: >-
            To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control, include this optional field and specify the current version
            of the custom attribute.
    RetrieveOrderCustomAttributeDefinitionResponse:
      type: object
      description: Represents a response from getting an order custom attribute definition.
      x-release-status: BETA
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The retrieved custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2022-10-06T16:53:23.141Z'
          description: The number of people seated at a table
          key: cover-count
          name: Cover count
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number
          updated_at: '2022-10-06T16:53:23.141Z'
          version: 1
          visibility: VISIBILITY_READ_WRITE_VALUES
    RetrieveOrderCustomAttributeRequest:
      type: object
      description: Represents a get request for an order custom attribute.
      x-release-status: BETA
      x-params-example: '?order_id=7BbXGEIWNldxAzrtGf9GPVZTwZ4F&key=cover-count'
      properties:
        version:
          type: integer
          description: >-
            To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control, include this optional field and specify the current version
            of the custom attribute.
        with_definition:
          type: boolean
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of each 

            custom attribute. Set this parameter to `true` to get the name and
            description of each custom attribute, 

            information about the data type, or other definition details. The
            default value is `false`.
          nullable: true
    RetrieveOrderCustomAttributeResponse:
      type: object
      description: Represents a response from getting an order custom attribute.
      x-release-status: BETA
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The retrieved custom attribute. If `with_definition` was set to
            `true` in the request, the custom attribute definition is returned
            in the `definition field.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute:
          created_at: '2022-11-22T21:27:33.429Z'
          key: cover-count
          updated_at: '2022-11-22T21:28:35.721Z'
          value: '6'
          version: 1
          visibility: VISIBILITY_READ_WRITE_VALUES
    RetrieveOrderRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
      example: {}
    RetrieveOrderResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        order:
          $ref: '#/components/schemas/Order'
          description: The requested order.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        order:
          created_at: '2020-05-18T16:30:49.614Z'
          discounts:
            - applied_money:
                amount: 550
                currency: USD
              name: 50% Off
              percentage: '50'
              scope: ORDER
              type: FIXED_PERCENTAGE
              uid: zGsRZP69aqSSR9lq9euSPB
          id: CAISENgvlJ6jLWAzERDzjyHVybY
          line_items:
            - applied_discounts:
                - applied_money:
                    amount: 250
                    currency: USD
                  discount_uid: zGsRZP69aqSSR9lq9euSPB
                  uid: 9zr9S4dxvPAixvn0lpa1VC
              base_price_money:
                amount: 500
                currency: USD
              gross_sales_money:
                amount: 500
                currency: USD
              name: Item 1
              quantity: '1'
              total_discount_money:
                amount: 250
                currency: USD
              total_money:
                amount: 250
                currency: USD
              total_service_charge_money:
                amount: 0
                currency: USD
              total_tax_money:
                amount: 0
                currency: USD
              uid: ULkg0tQTRK2bkU9fNv3IJD
              variation_total_price_money:
                amount: 500
                currency: USD
            - applied_discounts:
                - applied_money:
                    amount: 300
                    currency: USD
                  discount_uid: zGsRZP69aqSSR9lq9euSPB
                  uid: qa8LwwZK82FgSEkQc2HYVC
              base_price_money:
                amount: 300
                currency: USD
              gross_sales_money:
                amount: 600
                currency: USD
              name: Item 2
              quantity: '2'
              total_discount_money:
                amount: 300
                currency: USD
              total_money:
                amount: 300
                currency: USD
              total_service_charge_money:
                amount: 0
                currency: USD
              total_tax_money:
                amount: 0
                currency: USD
              uid: mumY8Nun4BC5aKe2yyx5a
              variation_total_price_money:
                amount: 600
                currency: USD
          location_id: D7AVYMEAPJ3A3
          net_amounts:
            discount_money:
              amount: 550
              currency: USD
            service_charge_money:
              amount: 0
              currency: USD
            tax_money:
              amount: 0
              currency: USD
            tip_money:
              amount: 0
              currency: USD
            total_money:
              amount: 550
              currency: USD
          state: OPEN
          total_discount_money:
            amount: 550
            currency: USD
          total_money:
            amount: 550
            currency: USD
          total_service_charge_money:
            amount: 0
            currency: USD
          total_tax_money:
            amount: 0
            currency: USD
          total_tip_money:
            amount: 0
            currency: USD
          updated_at: '2020-05-18T16:30:49.614Z'
          version: 1
    RetrievePaymentLinkRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
    RetrievePaymentLinkResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        payment_link:
          $ref: '#/components/schemas/PaymentLink'
          description: The payment link that is retrieved.
      example:
        payment_link:
          created_at: '2022-04-26T00:10:29Z'
          id: LLO5Q3FRCFICDB4B
          long_url: https://checkout.square.site/EXAMPLE
          order_id: 4uKASDATqSd1QQ9jV86sPhMdVEbSJc4F
          url: https://square.link/u/EXAMPLE
          version: 1
    RetrieveSnippetRequest:
      type: object
      description: Represents a `RetrieveSnippet` request.
      x-release-status: PUBLIC
      properties: {}
    RetrieveSnippetResponse:
      type: object
      description: >-
        Represents a `RetrieveSnippet` response. The response can include either
        `snippet` or `errors`.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        snippet:
          $ref: '#/components/schemas/Snippet'
          description: The retrieved snippet.
      example:
        snippet:
          content: <script>var js = 1;</script>
          created_at: '2021-03-11T25:40:09.000000Z'
          id: snippet_5d178150-a6c0-11eb-a9f1-437e6a2881e7
          site_id: site_278075276488921835
          updated_at: '2021-03-11T25:40:09.000000Z'
    RetrieveSubscriptionRequest:
      type: object
      description: >-
        Defines input parameters in a request to the 

        [RetrieveSubscription](api-endpoint:Subscriptions-RetrieveSubscription)
        endpoint.
      x-release-status: PUBLIC
      properties:
        include:
          type: string
          description: >-
            A query parameter to specify related information to be included in
            the response. 


            The supported query parameter values are: 


            - `actions`: to include scheduled actions on the targeted
            subscription.
          x-release-status: BETA
          nullable: true
    RetrieveSubscriptionResponse:
      type: object
      description: >-
        Defines output parameters in a response from the

        [RetrieveSubscription](api-endpoint:Subscriptions-RetrieveSubscription)
        endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered during the request.
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: The subscription retrieved.
      example:
        subscription:
          card_id: ccof:IkWfpLj4tNHMyFii3GB
          charged_through_date: '2023-11-20'
          created_at: '2022-07-27T21:53:10Z'
          customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4
          id: 8151fc89-da15-4eb9-a685-1a70883cebfc
          invoice_ids:
            - inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
            - inv:0-ChrcX_i3sNmfsHTGKhI4Wg2mceA
          location_id: S8GWD5R9QB376
          paid_until_date: '2024-08-01'
          plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
          price_override_money:
            amount: 25000
            currency: USD
          source:
            name: My Application
          start_date: '2022-07-27'
          status: ACTIVE
          timezone: America/Los_Angeles
    RetrieveTeamMemberBookingProfileRequest:
      type: object
      x-release-status: PUBLIC
      properties: {}
    RetrieveTeamMemberBookingProfileResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        team_member_booking_profile:
          $ref: '#/components/schemas/TeamMemberBookingProfile'
          description: The returned team member booking profile.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
      example:
        errors: []
        team_member_booking_profile:
          display_name: Sandbox Staff
          is_bookable: true
          team_member_id: TMaJcbiRqPIGZuS9
    RetrieveTeamMemberRequest:
      type: object
      description: Represents a retrieve request for a `TeamMember` object.
      x-release-status: PUBLIC
      properties: {}
      example: {}
    RetrieveTeamMemberResponse:
      type: object
      description: >-
        Represents a response from a retrieve request containing a `TeamMember`
        object or error messages.
      x-release-status: PUBLIC
      properties:
        team_member:
          $ref: '#/components/schemas/TeamMember'
          description: The successfully retrieved `TeamMember` object.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: The errors that occurred during the request.
      example:
        team_member:
          assigned_locations:
            assignment_type: EXPLICIT_LOCATIONS
            location_ids:
              - GA2Y9HSJ8KRYT
              - YSGH2WBKG94QZ
          created_at: '2021-06-11T22:55:45Z'
          email_address: joe_doe@example.com
          family_name: Doe
          given_name: Joe
          id: 1yJlHapkseYnNPETIU1B
          is_owner: false
          phone_number: '+14159283333'
          reference_id: reference_id_1
          status: ACTIVE
          updated_at: '2021-06-15T17:38:05Z'
          wage_setting:
            created_at: '2021-06-11T22:55:45Z'
            is_overtime_exempt: true
            job_assignments:
              - annual_rate:
                  amount: 3000000
                  currency: USD
                hourly_rate:
                  amount: 1443
                  currency: USD
                job_id: FjS8x95cqHiMenw4f1NAUH4P
                job_title: Manager
                pay_type: SALARY
                weekly_hours: 40
              - hourly_rate:
                  amount: 2000
                  currency: USD
                job_id: VDNpRv8da51NU8qZFC5zDWpF
                job_title: Cashier
                pay_type: HOURLY
            team_member_id: 1yJlHapkseYnNPETIU1B
            updated_at: '2021-06-11T22:55:45Z'
            version: 1
    RetrieveTokenStatusRequest:
      type: object
      description: Request object for [RetrieveTokenStatus] endpoint.
      x-release-status: PUBLIC
      properties: {}
    RetrieveTokenStatusResponse:
      type: object
      description: |-
        Defines the fields that are included in the response body of
        a request to the `RetrieveTokenStatus` endpoint.
      x-release-status: PUBLIC
      properties:
        scopes:
          type: array
          items:
            type: string
          description: The list of scopes associated with an access token.
        expires_at:
          type: string
          description: >-
            The date and time when the `access_token` expires, in RFC 3339
            format. Empty if the token never expires.
        client_id:
          type: string
          description: >-
            The Square-issued application ID associated with the access token.
            This is the same application ID used to obtain the token.
          maxLength: 191
        merchant_id:
          type: string
          description: The ID of the authorizing merchant's business.
          minLength: 8
          maxLength: 191
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: ' Any errors that occurred during the request.'
      example:
        client_id: CLIENT_ID
        expires_at: '2022-10-14T14:44:00Z'
        merchant_id: MERCHANT_ID
        scopes:
          - PAYMENTS_READ
          - PAYMENTS_WRITE
    RetrieveTransactionRequest:
      type: object
      x-release-status: DEPRECATED
      properties: {}
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/RetrieveTransaction/RetrieveTransactionRequest.csharp
        java: /sdk_samples/RetrieveTransaction/RetrieveTransactionRequest.java
        javascript: /sdk_samples/RetrieveTransaction/RetrieveTransactionRequest.javascript
        php: /sdk_samples/RetrieveTransaction/RetrieveTransactionRequest.php
        python: /sdk_samples/RetrieveTransaction/RetrieveTransactionRequest.python
        ruby: /sdk_samples/RetrieveTransaction/RetrieveTransactionRequest.ruby
    RetrieveTransactionResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [RetrieveTransaction](api-endpoint:Transactions-RetrieveTransaction)
        endpoint.


        One of `errors` or `transaction` is present in a given response (never
        both).
      x-release-status: DEPRECATED
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        transaction:
          $ref: '#/components/schemas/Transaction'
          description: The requested transaction.
      example:
        transaction:
          created_at: '2016-03-10T22:57:56Z'
          id: KnL67ZIwXCPtzOrqj0HrkxMF
          location_id: 18YC4JDH91E1H
          product: EXTERNAL_API
          reference_id: some optional reference id
          tenders:
            - additional_recipients:
                - amount_money:
                    amount: 20
                    currency: USD
                  description: Application fees
                  location_id: 057P5VYJ4A5X1
              amount_money:
                amount: 5000
                currency: USD
              card_details:
                card:
                  card_brand: VISA
                  last_4: '1111'
                entry_method: KEYED
                status: CAPTURED
              created_at: '2016-03-10T22:57:56Z'
              id: MtZRYYdDrYNQbOvV7nbuBvMF
              location_id: 18YC4JDH91E1H
              note: some optional note
              processing_fee_money:
                amount: 138
                currency: USD
              transaction_id: KnL67ZIwXCPtzOrqj0HrkxMF
              type: CARD
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/RetrieveTransaction/RetrieveTransactionResponse.csharp
        java: /sdk_samples/RetrieveTransaction/RetrieveTransactionResponse.java
        javascript: >-
          /sdk_samples/RetrieveTransaction/RetrieveTransactionResponse.javascript
        php: /sdk_samples/RetrieveTransaction/RetrieveTransactionResponse.php
        python: /sdk_samples/RetrieveTransaction/RetrieveTransactionResponse.python
        ruby: /sdk_samples/RetrieveTransaction/RetrieveTransactionResponse.ruby
    RetrieveVendorRequest:
      type: object
      description: >-
        Represents an input to a call to
        [RetrieveVendor](api-endpoint:Vendors-RetrieveVendor).
      x-release-status: BETA
      properties: {}
    RetrieveVendorResponse:
      type: object
      description: >-
        Represents an output from a call to
        [RetrieveVendor](api-endpoint:Vendors-RetrieveVendor).
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered when the request fails.
        vendor:
          $ref: '#/components/schemas/Vendor'
          description: The successfully retrieved [Vendor](entity:Vendor) object.
      example:
        vendor:
          account_number: '4025391'
          address:
            address_line_1: 505 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          contacts:
            - email_address: joe@joesfreshseafood.com
              id: INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A
              name: Joe Burrow
              phone_number: 1-212-555-4250
          created_at: '2022-03-16T10:21:54.859Z'
          id: INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4
          name: Joe's Fresh Seafood
          note: a vendor
          status: ACTIVE
          updated_at: '2022-03-16T10:21:54.859Z'
          version: 1
    RetrieveWageSettingRequest:
      type: object
      description: Represents a retrieve request for the wage setting of a team member.
      x-release-status: PUBLIC
      properties: {}
      example: {}
    RetrieveWageSettingResponse:
      type: object
      description: >-
        Represents a response from a retrieve request containing the specified
        `WageSetting` object or error messages.
      x-release-status: PUBLIC
      properties:
        wage_setting:
          $ref: '#/components/schemas/WageSetting'
          description: The successfully retrieved `WageSetting` object.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: The errors that occurred during the request.
      example:
        wage_setting:
          created_at: '2020-06-11T23:01:21+00:00'
          is_overtime_exempt: false
          job_assignments:
            - annual_rate:
                amount: 4500000
                currency: USD
              hourly_rate:
                amount: 2164
                currency: USD
              job_title: Manager
              pay_type: SALARY
              weekly_hours: 40
          team_member_id: 1yJlHapkseYnNPETIU1B
          updated_at: '2020-06-11T23:01:21+00:00'
          version: 1
    RetrieveWebhookSubscriptionRequest:
      type: object
      description: Retrieves a [Subscription](entity:WebhookSubscription) using its id.
      x-release-status: PUBLIC
      properties: {}
    RetrieveWebhookSubscriptionResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [RetrieveWebhookSubscription](api-endpoint:WebhookSubscriptions-RetrieveWebhookSubscription)
        endpoint.


        Note: if there are errors processing the request, the
        [Subscription](entity:WebhookSubscription) will not be

        present.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        subscription:
          $ref: '#/components/schemas/WebhookSubscription'
          description: The requested [Subscription](entity:WebhookSubscription).
      example:
        subscription:
          api_version: '2021-12-15'
          created_at: 2022-01-10 23:29:48 +0000 UTC
          enabled: true
          event_types:
            - payment.created
            - payment.updated
          id: wbhk_b35f6b3145074cf9ad513610786c19d5
          name: Example Webhook Subscription
          notification_url: https://example-webhook-url.com
          signature_key: 1k9bIJKCeTmSQwyagtNRLg
          updated_at: 2022-01-10 23:29:48 +0000 UTC
    RevokeTokenRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        client_id:
          type: string
          description: >-
            The Square-issued ID for your application, which is available on the
            **OAuth** page in the

            [Developer Dashboard](https://developer.squareup.com/apps).
          maxLength: 191
          nullable: true
        access_token:
          type: string
          description: >-
            The access token of the merchant whose token you want to revoke.

            Do not provide a value for `merchant_id` if you provide this
            parameter.
          minLength: 2
          maxLength: 1024
          nullable: true
        merchant_id:
          type: string
          description: >-
            The ID of the merchant whose token you want to revoke.

            Do not provide a value for `access_token` if you provide this
            parameter.
          nullable: true
        revoke_only_access_token:
          type: boolean
          description: |-
            If `true`, terminate the given single access token, but do not
            terminate the entire authorization.
            Default: `false`
          nullable: true
      example:
        access_token: ACCESS_TOKEN
        client_id: CLIENT_ID
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/RevokeToken/RevokeTokenRequest.csharp
        java: /sdk_samples/RevokeToken/RevokeTokenRequest.java
        javascript: /sdk_samples/RevokeToken/RevokeTokenRequest.javascript
        php: /sdk_samples/RevokeToken/RevokeTokenRequest.php
        python: /sdk_samples/RevokeToken/RevokeTokenRequest.python
        ruby: /sdk_samples/RevokeToken/RevokeTokenRequest.ruby
    RevokeTokenResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        success:
          type: boolean
          description: If the request is successful, this is `true`.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        success: true
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/RevokeToken/RevokeTokenResponse.csharp
        java: /sdk_samples/RevokeToken/RevokeTokenResponse.java
        javascript: /sdk_samples/RevokeToken/RevokeTokenResponse.javascript
        php: /sdk_samples/RevokeToken/RevokeTokenResponse.php
        python: /sdk_samples/RevokeToken/RevokeTokenResponse.python
        ruby: /sdk_samples/RevokeToken/RevokeTokenResponse.ruby
    RiskEvaluation:
      type: object
      description: >-
        Represents fraud risk information for the associated payment.


        When you take a payment through Square's Payments API (using the
        `CreatePayment`

        endpoint), Square evaluates it and assigns a risk level to the payment.
        Sellers

        can use this information to determine the course of action (for example,

        provide the goods/services or refund the payment).
      x-release-status: BETA
      required:
        - status
      properties:
        created_at:
          type: string
          description: The timestamp when payment risk was evaluated, in RFC 3339 format.
          readOnly: true
        risk_level:
          $ref: '#/components/schemas/RiskEvaluationRiskLevel'
          description: >-
            The risk level associated with the payment

            See [RiskEvaluationRiskLevel](#type-riskevaluationrisklevel) for
            possible values
          nullable: true
    RiskEvaluationRiskLevel:
      type: string
      enum:
        - PENDING
        - NORMAL
        - MODERATE
        - HIGH
      x-enum-elements:
        - name: PENDING
          description: Indicates Square is still evaluating the payment.
        - name: NORMAL
          description: Indicates payment risk is within the normal range.
        - name: MODERATE
          description: Indicates elevated risk level associated with the payment.
        - name: HIGH
          description: Indicates significantly elevated risk level with the payment.
      x-release-status: BETA
    SaveCardOptions:
      type: object
      description: Describes save-card action fields.
      x-release-status: BETA
      required:
        - customer_id
      properties:
        customer_id:
          type: string
          description: The square-assigned ID of the customer linked to the saved card.
        card_id:
          type: string
          description: The id of the created card-on-file.
          maxLength: 64
          readOnly: true
        reference_id:
          type: string
          description: >-
            An optional user-defined reference ID that can be used to associate

            this `Card` to another entity in an external system. For example, a
            customer

            ID generated by a third-party system.
          maxLength: 128
          nullable: true
    SearchAvailabilityFilter:
      type: object
      description: A query filter to search for buyer-accessible availabilities by.
      x-release-status: PUBLIC
      required:
        - start_at_range
      properties:
        start_at_range:
          $ref: '#/components/schemas/TimeRange'
          description: >-
            The query expression to search for buy-accessible availabilities
            with their starting times falling within the specified time range.

            The time range must be at least 24 hours and at most 32 days long.

            For waitlist availabilities, the time range can be 0 or more up to
            367 days long.
        location_id:
          type: string
          description: >-
            The query expression to search for buyer-accessible availabilities
            with their location IDs matching the specified location ID.

            This query expression cannot be set if `booking_id` is set.
          maxLength: 32
          nullable: true
        segment_filters:
          type: array
          items:
            $ref: '#/components/schemas/SegmentFilter'
          description: >-
            The query expression to search for buyer-accessible availabilities
            matching the specified list of segment filters.

            If the size of the `segment_filters` list is `n`, the search returns
            availabilities with `n` segments per availability.


            This query expression cannot be set if `booking_id` is set.
          nullable: true
        booking_id:
          type: string
          description: >-
            The query expression to search for buyer-accessible availabilities
            for an existing booking by matching the specified `booking_id`
            value.

            This is commonly used to reschedule an appointment.

            If this expression is set, the `location_id` and `segment_filters`
            expressions cannot be set.
          maxLength: 36
          nullable: true
    SearchAvailabilityQuery:
      type: object
      description: >-
        The query used to search for buyer-accessible availabilities of
        bookings.
      x-release-status: PUBLIC
      required:
        - filter
      properties:
        filter:
          $ref: '#/components/schemas/SearchAvailabilityFilter'
          description: >-
            The query filter to search for buyer-accessible availabilities of
            existing bookings.
    SearchAvailabilityRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - query
      properties:
        query:
          $ref: '#/components/schemas/SearchAvailabilityQuery'
          description: >-
            Query conditions used to filter buyer-accessible booking
            availabilities.
    SearchAvailabilityResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        availabilities:
          type: array
          items:
            $ref: '#/components/schemas/Availability'
          description: List of appointment slots available for booking.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
      example:
        availabilities:
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMXUrsBWWcHTt79t
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-26T13:00:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMXUrsBWWcHTt79t
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-26T13:30:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMaJcbiRqPIGZuS9
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-26T14:00:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMaJcbiRqPIGZuS9
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-26T14:30:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMaJcbiRqPIGZuS9
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-26T15:00:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMaJcbiRqPIGZuS9
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-26T15:30:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMaJcbiRqPIGZuS9
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-26T16:00:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMXUrsBWWcHTt79t
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-27T09:00:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMaJcbiRqPIGZuS9
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-27T09:30:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMXUrsBWWcHTt79t
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-27T10:00:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMXUrsBWWcHTt79t
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-27T10:30:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMXUrsBWWcHTt79t
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-27T11:00:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMaJcbiRqPIGZuS9
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-27T11:30:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMaJcbiRqPIGZuS9
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-27T12:00:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMaJcbiRqPIGZuS9
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-27T12:30:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMXUrsBWWcHTt79t
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-27T13:00:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMXUrsBWWcHTt79t
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-27T13:30:00Z'
          - appointment_segments:
              - duration_minutes: 60
                service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
                service_variation_version: 1599775456731
                team_member_id: TMaJcbiRqPIGZuS9
            location_id: LEQHH0YY8B42M
            start_at: '2020-11-27T14:00:00Z'
        errors: []
    SearchCatalogItemsRequest:
      type: object
      description: >-
        Defines the request body for the
        [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) endpoint.
      x-release-status: PUBLIC
      properties:
        text_filter:
          type: string
          description: >-
            The text filter expression to return items or item variations
            containing specified text in

            the `name`, `description`, or `abbreviation` attribute value of an
            item, or in

            the `name`, `sku`, or `upc` attribute value of an item variation.
        category_ids:
          type: array
          items:
            type: string
          description: >-
            The category id query expression to return items containing the
            specified category IDs.
        stock_levels:
          type: array
          items:
            $ref: '#/components/schemas/SearchCatalogItemsRequestStockLevel'
          description: >-
            The stock-level query expression to return item variations with the
            specified stock levels.

            See
            [SearchCatalogItemsRequestStockLevel](#type-searchcatalogitemsrequeststocklevel)
            for possible values
        enabled_location_ids:
          type: array
          items:
            type: string
          description: >-
            The enabled-location query expression to return items and item
            variations having specified enabled locations.
        cursor:
          type: string
          description: >-
            The pagination token, returned in the previous response, used to
            fetch the next batch of pending results.
        limit:
          type: integer
          description: >-
            The maximum number of results to return per page. The default value
            is 100.
          maximum: 100
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: >-
            The order to sort the results by item names. The default sort order
            is ascending (`ASC`).

            See [SortOrder](#type-sortorder) for possible values
        product_types:
          type: array
          items:
            $ref: '#/components/schemas/CatalogItemProductType'
          description: >-
            The product types query expression to return items or item
            variations having the specified product types.
        custom_attribute_filters:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttributeFilter'
          description: >-
            The customer-attribute filter to return items or item variations
            matching the specified

            custom attribute expressions. A maximum number of 10 custom
            attribute expressions are supported in

            a single call to the
            [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems)
            endpoint.
        archived_state:
          $ref: '#/components/schemas/ArchivedState'
          description: >-
            The query filter to return not archived
            (`ARCHIVED_STATE_NOT_ARCHIVED`), archived
            (`ARCHIVED_STATE_ARCHIVED`), or either type (`ARCHIVED_STATE_ALL`)
            of items.
      example:
        category_ids:
          - WINE_CATEGORY_ID
        custom_attribute_filters:
          - bool_filter: true
            custom_attribute_definition_id: VEGAN_DEFINITION_ID
          - custom_attribute_definition_id: BRAND_DEFINITION_ID
            string_filter: Dark Horse
          - key: VINTAGE
            number_filter:
              max: 2018
              min: 2017
          - custom_attribute_definition_id: VARIETAL_DEFINITION_ID
            selection_ids_filter: MERLOT_SELECTION_ID
        enabled_location_ids:
          - ATL_LOCATION_ID
        limit: 100
        product_types:
          - REGULAR
        sort_order: ASC
        stock_levels:
          - OUT
          - LOW
        text_filter: red
    SearchCatalogItemsRequestStockLevel:
      type: string
      enum:
        - OUT
        - LOW
      x-enum-elements:
        - name: OUT
          description: The item inventory is empty.
        - name: LOW
          description: The item inventory is low.
      description: Defines supported stock levels of the item inventory.
      x-release-status: PUBLIC
    SearchCatalogItemsResponse:
      type: object
      description: >-
        Defines the response body returned from the
        [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems) endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        items:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: Returned items matching the specified query expressions.
        cursor:
          type: string
          description: >-
            Pagination token used in the next request to return more of the
            search result.
        matched_variation_ids:
          type: array
          items:
            type: string
          description: >-
            Ids of returned item variations matching the specified query
            expression.
      example:
        items:
          - custom_attribute_values:
              BRAND:
                custom_attribute_definition_id: BRAND_DEFINITION_ID
                key: BRAND
                name: Brand
                string_value: Dark Horse
                type: STRING
              VARIETAL:
                custom_attribute_definition_id: VARIETAL_DEFINITION_ID
                key: VARIETAL
                name: Varietal
                selection_uid_values:
                  - MERLOT_SELECTION_ID
                  - null
                type: SELECTION
              VINTAGE:
                custom_attribute_definition_id: EI7IJQDUKYSHULREPIPH6HNU
                key: VINTAGE
                name: Vintage
                number_value: 2018
                type: NUMBER
            id: GPOKJPTV2KDLVKCADJ7I77EZ
            is_deleted: false
            item_data:
              description: A nice red wine
              is_archived: false
              name: Dark Horse Merlot 2018
              product_type: REGULAR
              variations:
                - id: VBJNPHCOKDFECR6VU25WRJUD
                  is_deleted: false
                  item_variation_data:
                    item_id: GPOKJPTV2KDLVKCADJ7I77EZ
                    name: 750 mL
                    ordinal: 0
                    price_money:
                      amount: 1000
                      currency: USD
                    pricing_type: FIXED_PRICING
                  present_at_all_locations: true
                  type: ITEM_VARIATION
                  updated_at: '2020-06-18T17:55:56.646Z'
                  version: 1592502956646
            present_at_all_locations: true
            type: ITEM
            updated_at: '2020-06-18T17:55:56.646Z'
            version: 1592502956646
        matched_variation_ids:
          - VBJNPHCOKDFECR6VU25WRJUD
    SearchCatalogObjectsRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: >-
            The pagination cursor returned in the previous response. Leave unset
            for an initial request.

            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
        object_types:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObjectType'
          description: >-
            The desired set of object types to appear in the search results.


            If this is unspecified, the operation returns objects of all the top
            level types at the version

            of the Square API used to make the request. Object types that are
            nested onto other object types

            are not included in the defaults.


            At the current API version the default object types are:

            ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, 

            PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,

            SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION,
            QUICK_AMOUNT_SETTINGS.


            Note that if you wish for the query to return objects belonging to
            nested types (i.e., COMPONENT, IMAGE,

            ITEM_OPTION_VAL, ITEM_VARIATION, or MODIFIER), you must explicitly
            include all the types of interest

            in this field.
        include_deleted_objects:
          type: boolean
          description: >-
            If `true`, deleted objects will be included in the results. Defaults
            to `false`. Deleted objects will have their `is_deleted` field set
            to `true`. If `include_deleted_objects` is `true`, then the
            `include_category_path_to_root` request parameter must be `false`.
            Both properties cannot be `true` at the same time.
        include_related_objects:
          type: boolean
          description: >-
            If `true`, the response will include additional objects that are
            related to the

            requested objects. Related objects are objects that are referenced
            by object ID by the objects

            in the response. This is helpful if the objects are being fetched
            for immediate display to a user.

            This process only goes one level deep. Objects referenced by the
            related objects will not be included.

            For example:


            If the `objects` field of the response contains a CatalogItem, its
            associated

            CatalogCategory objects, CatalogTax objects, CatalogImage objects
            and

            CatalogModifierLists will be returned in the `related_objects` field
            of the

            response. If the `objects` field of the response contains a
            CatalogItemVariation,

            its parent CatalogItem will be returned in the `related_objects`
            field of

            the response.


            Default value: `false`
        begin_time:
          type: string
          description: >-
            Return objects modified after this
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates),
            in RFC 3339

            format, e.g., `2016-09-04T23:59:33.123Z`. The timestamp is exclusive
            - objects with a

            timestamp equal to `begin_time` will not be included in the
            response.
        query:
          $ref: '#/components/schemas/CatalogQuery'
          description: >-
            A query to be used to filter or sort the results. If no query is
            specified, the entire catalog will be returned.
        limit:
          type: integer
          description: >-
            A limit on the number of results to be returned in a single page.
            The limit is advisory -

            the implementation may return more or fewer results. If the supplied
            limit is negative, zero, or

            is higher than the maximum limit of 1,000, it will be ignored.
        include_category_path_to_root:
          type: boolean
          description: >-
            Specifies whether or not to include the `path_to_root` list for each
            returned category instance. The `path_to_root` list consists of
            `CategoryPathToRootNode` objects and specifies the path that starts
            with the immediate parent category of the returned category and ends
            with its root category. If the returned category is a top-level
            category, the `path_to_root` list is empty and is not returned in
            the response payload. If `include_category_path_to_root` is `true`,
            then the `include_deleted_objects` request parameter must be
            `false`. Both properties cannot be `true` at the same time.
      example:
        limit: 100
        object_types:
          - ITEM
        query:
          prefix_query:
            attribute_name: name
            attribute_prefix: tea
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsRequest.csharp
        java: >-
          /sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsRequest.java
        javascript: >-
          /sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsRequest.javascript
        php: >-
          /sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsRequest.php
        python: >-
          /sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsRequest.python
        ruby: >-
          /sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsRequest.ruby
    SearchCatalogObjectsResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If unset,
            this is the final response.

            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
        objects:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: The CatalogObjects returned.
        related_objects:
          type: array
          items:
            $ref: '#/components/schemas/CatalogObject'
          description: >-
            A list of CatalogObjects referenced by the objects in the `objects`
            field.
        latest_time:
          type: string
          description: >-
            When the associated product catalog was last updated. Will

            match the value for `end_time` or `cursor` if either field is
            included in the `SearchCatalog` request.
          x-release-status: BETA
      example:
        objects:
          - id: X5DZ5NWWAQ44CKBLKIFQGOWK
            is_deleted: false
            item_data:
              categories:
                - id: E7CLE5RZZ744BHWVQQEAHI2C
                  ordinal: 0
              description: A delicious blend of black tea.
              name: Tea - Black
              product_type: REGULAR
              tax_ids:
                - ZXITPM6RWHZ7GZ7EIP3YKECM
              variations:
                - id: 5GSZPX6EU7MM75S57OONG3V5
                  is_deleted: false
                  item_variation_data:
                    item_id: X5DZ5NWWAQ44CKBLKIFQGOWK
                    name: Regular
                    ordinal: 1
                    price_money:
                      amount: 150
                      currency: USD
                    pricing_type: FIXED_PRICING
                  present_at_all_locations: true
                  type: ITEM_VARIATION
                  updated_at: '2017-10-26T15:27:31.626Z'
                  version: 1509031651626
                - id: XVLBN7DU6JTWHJTG5F265B43
                  is_deleted: false
                  item_variation_data:
                    item_id: X5DZ5NWWAQ44CKBLKIFQGOWK
                    name: Large
                    ordinal: 2
                    price_money:
                      amount: 225
                      currency: USD
                    pricing_type: FIXED_PRICING
                  present_at_all_locations: true
                  type: ITEM_VARIATION
                  updated_at: '2017-10-26T15:27:31.626Z'
                  version: 1509031651626
              visibility: PRIVATE
            present_at_all_locations: true
            type: ITEM
            updated_at: '2017-10-26T15:41:32.337Z'
            version: 1509032492337
          - id: NNNEM3LA656Q46NXLWCNI7S5
            is_deleted: false
            item_data:
              categories:
                - id: E7CLE5RZZ744BHWVQQEAHI2C
                  ordinal: 0
              description: Relaxing green herbal tea.
              name: Tea - Green
              product_type: REGULAR
              tax_ids:
                - ZXITPM6RWHZ7GZ7EIP3YKECM
              variations:
                - id: FHYBVIA6NVBCSOVETA62WEA4
                  is_deleted: false
                  item_variation_data:
                    item_id: NNNEM3LA656Q46NXLWCNI7S5
                    name: Regular
                    ordinal: 1
                    price_money:
                      amount: 150
                      currency: USD
                    pricing_type: FIXED_PRICING
                  present_at_all_locations: true
                  type: ITEM_VARIATION
                  updated_at: '2017-10-26T15:29:00.524Z'
                  version: 1509031740524
              visibility: PRIVATE
            present_at_all_locations: true
            type: ITEM
            updated_at: '2017-10-26T15:41:23.232Z'
            version: 1509032483232
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsResponse.csharp
        java: >-
          /sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsResponse.java
        javascript: >-
          /sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsResponse.javascript
        php: >-
          /sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsResponse.php
        python: >-
          /sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsResponse.python
        ruby: >-
          /sdk_samples/Catalog/SearchCatalogObjects/SearchCatalogObjectsResponse.ruby
    SearchCustomersRequest:
      type: object
      description: >-
        Defines the fields that are included in the request body of a request to
        the

        `SearchCustomers` endpoint.
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: >-
            Include the pagination cursor in subsequent calls to this endpoint
            to retrieve

            the next set of results associated with the original query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        limit:
          type: integer
          description: >-
            The maximum number of results to return in a single page. This limit
            is advisory. The response might contain more or fewer results.

            If the specified limit is invalid, Square returns a `400
            VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value is
            100.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          format: int64
          minimum: 1
          maximum: 100
        query:
          $ref: '#/components/schemas/CustomerQuery'
          description: >-
            The filtering and sorting criteria for the search request. If a
            query is not specified,

            Square returns all customer profiles ordered alphabetically by
            `given_name` and `family_name`.
        count:
          type: boolean
          description: >-
            Indicates whether to return the total count of matching customers in
            the `count` field of the response.


            The default value is `false`.
      example:
        limit: 2
        query:
          filter:
            created_at:
              end_at: '2018-02-01T00:00:00-00:00'
              start_at: '2018-01-01T00:00:00-00:00'
            creation_source:
              rule: INCLUDE
              values:
                - THIRD_PARTY
            email_address:
              fuzzy: example.com
            group_ids:
              all:
                - 545AXB44B4XXWMVQ4W8SBT3HHF
          sort:
            field: CREATED_AT
            order: ASC
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/SearchCustomers/SearchCustomersRequest.csharp
        java: /sdk_samples/SearchCustomers/SearchCustomersRequest.java
        javascript: /sdk_samples/SearchCustomers/SearchCustomersRequest.javascript
        php: /sdk_samples/SearchCustomers/SearchCustomersRequest.php
        python: /sdk_samples/SearchCustomers/SearchCustomersRequest.python
        ruby: /sdk_samples/SearchCustomers/SearchCustomersRequest.ruby
    SearchCustomersResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the `SearchCustomers` endpoint.


        Either `errors` or `customers` is present in a given response (never
        both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        customers:
          type: array
          items:
            $ref: '#/components/schemas/Customer'
          description: >-
            The customer profiles that match the search query. If any search
            condition is not met, the result is an empty object (`{}`).

            Only customer profiles with public information (`given_name`,
            `family_name`, `company_name`, `email_address`, or `phone_number`)

            are included in the response.
        cursor:
          type: string
          description: >-
            A pagination cursor that can be used during subsequent calls

            to `SearchCustomers` to retrieve the next set of results associated

            with the original query. Pagination cursors are only present when

            a request succeeds and additional results are available.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        count:
          type: integer
          description: >-
            The total count of customers associated with the Square account that
            match the search query. Only customer profiles with

            public information (`given_name`, `family_name`, `company_name`,
            `email_address`, or `phone_number`) are counted. This field is

            present only if `count` is set to `true` in the request.
          format: int64
      example:
        cursor: 9dpS093Uy12AzeE
        customers:
          - address:
              address_line_1: 505 Electric Ave
              address_line_2: Suite 600
              administrative_district_level_1: NY
              country: US
              locality: New York
              postal_code: '10003'
            created_at: '2018-01-23T20:21:54.859Z'
            creation_source: DIRECTORY
            email_address: james.bond@example.com
            family_name: Bond
            given_name: James
            group_ids:
              - 545AXB44B4XXWMVQ4W8SBT3HHF
            id: JDKYHBWT1D4F8MFH63DBMEN8Y4
            phone_number: +1-212-555-4250
            preferences:
              email_unsubscribed: false
            reference_id: YOUR_REFERENCE_ID_2
            segment_ids:
              - 1KB9JE5EGJXCW.REACHABLE
            updated_at: '2020-04-20T10:02:43.083Z'
            version: 7
          - address:
              address_line_1: 500 Electric Ave
              address_line_2: Suite 600
              administrative_district_level_1: NY
              country: US
              locality: New York
              postal_code: '10003'
            created_at: '2018-01-30T14:10:54.859Z'
            creation_source: THIRD_PARTY
            email_address: amelia.earhart@example.com
            family_name: Earhart
            given_name: Amelia
            group_ids:
              - 545AXB44B4XXWMVQ4W8SBT3HHF
            id: A9641GZW2H7Z56YYSD41Q12HDW
            note: a customer
            phone_number: +1-212-555-9238
            preferences:
              email_unsubscribed: false
            reference_id: YOUR_REFERENCE_ID_1
            segment_ids:
              - 1KB9JE5EGJXCW.REACHABLE
            updated_at: '2018-03-08T18:25:21.342Z'
            version: 1
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/SearchCustomers/SearchCustomersResponse.csharp
        java: /sdk_samples/SearchCustomers/SearchCustomersResponse.java
        javascript: /sdk_samples/SearchCustomers/SearchCustomersResponse.javascript
        php: /sdk_samples/SearchCustomers/SearchCustomersResponse.php
        python: /sdk_samples/SearchCustomers/SearchCustomersResponse.python
        ruby: /sdk_samples/SearchCustomers/SearchCustomersResponse.ruby
    SearchEventsFilter:
      type: object
      description: Criteria to filter events by.
      x-release-status: BETA
      properties:
        event_types:
          type: array
          items:
            type: string
          description: Filter events by event types.
          nullable: true
        merchant_ids:
          type: array
          items:
            type: string
          description: Filter events by merchant.
          nullable: true
        location_ids:
          type: array
          items:
            type: string
          description: Filter events by location.
          nullable: true
        created_at:
          $ref: '#/components/schemas/TimeRange'
          description: Filter events by when they were created.
    SearchEventsQuery:
      type: object
      description: Contains query criteria for the search.
      x-release-status: BETA
      properties:
        filter:
          $ref: '#/components/schemas/SearchEventsFilter'
          description: Criteria to filter events by.
          nullable: true
        sort:
          $ref: '#/components/schemas/SearchEventsSort'
          description: Criteria to sort events by.
          nullable: true
    SearchEventsRequest:
      type: object
      description: Searches [Event](entity:Event)s for your application.
      x-release-status: BETA
      properties:
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.
            Provide this cursor to retrieve the next set of events for your
            original query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          maxLength: 256
        limit:
          type: integer
          description: >-
            The maximum number of events to return in a single page. The
            response might contain fewer events. The default value is 100, which
            is also the maximum allowed value.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).


            Default: 100
          minimum: 1
          maximum: 100
        query:
          $ref: '#/components/schemas/SearchEventsQuery'
          description: >-
            The filtering and sorting criteria for the search request. To
            retrieve additional pages using a cursor, you must use the original
            query.
    SearchEventsResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [SearchEvents](api-endpoint:Events-SearchEvents)
        endpoint.


        Note: if there are errors processing the request, the events field will
        not be

        present.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
          description: The list of [Event](entity:Event)s returned by the search.
        metadata:
          type: array
          items:
            $ref: '#/components/schemas/EventMetadata'
          description: >-
            Contains the metadata of an event. For more information, see
            [Event](entity:Event).
        cursor:
          type: string
          description: >-
            When a response is truncated, it includes a cursor that you can use
            in a subsequent request to fetch the next set of events. If empty,
            this is the final response.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        cursor: 6b571fc9773647f=
        events:
          - created_at: '2022-04-26T10:08:40.454726'
            data:
              id: ORSEVtZAJxb37RA1EiGw
              object:
                dispute:
                  amount_money:
                    amount: 8801
                    currency: USD
                  brand_dispute_id: r9rKGSBBQbywBNnWWIiGFg
                  card_brand: VISA
                  created_at: '2020-02-19T21:24:53.258Z'
                  disputed_payment:
                    payment_id: fbmsaEOpoARDKxiSGH1fqPuqoqFZY
                  due_at: '2020-03-04T00:00:00.000Z'
                  id: ORSEVtZAJxb37RA1EiGw
                  location_id: VJDQQP3CG14EY
                  reason: AMOUNT_DIFFERS
                  reported_at: '2020-02-19T00:00:00.000Z'
                  state: WON
                  updated_at: '2020-02-19T21:34:41.851Z'
                  version: 6
              type: dispute
            event_id: 73ecd468-0aba-424f-b862-583d44efe7c8
            location_id: VJDQQP3CG14EY
            merchant_id: 0HPGX5JYE6EE1
            type: dispute.state.updated
        metadata:
          - api_version: '2022-12-13'
            event_id: 73ecd468-0aba-424f-b862-583d44efe7c8
    SearchEventsSort:
      type: object
      description: Criteria to sort events by.
      x-release-status: BETA
      properties:
        field:
          $ref: '#/components/schemas/SearchEventsSortField'
          description: >-
            Sort events by event types.

            See [SearchEventsSortField](#type-searcheventssortfield) for
            possible values
          nullable: true
        order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            The order to use for sorting the events.
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
    SearchEventsSortField:
      type: string
      enum:
        - DEFAULT
      x-enum-elements:
        - name: DEFAULT
          description: >-
            Use the default sort key. The default behavior is to sort events by
            when they were created (`created_at`).
      description: Specifies the sort key for events returned from a search.
      x-release-status: BETA
    SearchInvoicesRequest:
      type: object
      description: Describes a `SearchInvoices` request.
      x-release-status: PUBLIC
      required:
        - query
      properties:
        query:
          $ref: '#/components/schemas/InvoiceQuery'
          description: Describes the query criteria for searching invoices.
        limit:
          type: integer
          description: >-
            The maximum number of invoices to return (200 is the maximum
            `limit`). 

            If not provided, the server uses a default limit of 100 invoices.
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint. 

            Provide this cursor to retrieve the next set of results for your
            original query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        query:
          filter:
            customer_ids:
              - JDKYHBWT1D4F8MFH63DBMEN8Y4
            location_ids:
              - ES0RJRZYEC39A
          limit: 100
          sort:
            field: INVOICE_SORT_DATE
            order: DESC
    SearchInvoicesResponse:
      type: object
      description: Describes a `SearchInvoices` response.
      x-release-status: PUBLIC
      properties:
        invoices:
          type: array
          items:
            $ref: '#/components/schemas/Invoice'
          description: The list of invoices returned by the search.
        cursor:
          type: string
          description: >-
            When a response is truncated, it includes a cursor that you can use
            in a 

            subsequent request to fetch the next set of invoices. If empty, this
            is the final 

            response. 

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example:
        cursor: ChoIDhIWVm54ZVRhLXhySFBOejBBM2xJb2daUQoFCI4IGAE
        invoices:
          - accepted_payment_methods:
              bank_account: false
              buy_now_pay_later: false
              card: true
              cash_app_pay: false
              square_gift_card: false
            created_at: '2020-06-18T17:45:13Z'
            custom_fields:
              - label: Event Reference Number
                placement: ABOVE_LINE_ITEMS
                value: 'Ref. #1234'
              - label: Terms of Service
                placement: BELOW_LINE_ITEMS
                value: The terms of service are...
            delivery_method: EMAIL
            description: We appreciate your business!
            id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
            invoice_number: inv-100
            location_id: ES0RJRZYEC39A
            order_id: CAISENgvlJ6jLWAzERDzjyHVybY
            payment_requests:
              - automatic_payment_source: NONE
                computed_amount_money:
                  amount: 10000
                  currency: USD
                due_date: '2030-01-24'
                reminders:
                  - message: Your invoice is due tomorrow
                    relative_scheduled_days: -1
                    status: PENDING
                    uid: beebd363-e47f-4075-8785-c235aaa7df11
                request_type: BALANCE
                tipping_enabled: true
                total_completed_amount_money:
                  amount: 0
                  currency: USD
                uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355
            primary_recipient:
              customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4
              email_address: Amelia.Earhart@example.com
              family_name: Earhart
              given_name: Amelia
              phone_number: 1-212-555-4240
            sale_or_service_date: '2030-01-24'
            scheduled_at: '2030-01-13T10:00:00Z'
            status: DRAFT
            store_payment_method_enabled: false
            timezone: America/Los_Angeles
            title: Event Planning Services
            updated_at: '2020-06-18T17:45:13Z'
            version: 0
          - accepted_payment_methods:
              bank_account: false
              buy_now_pay_later: false
              card: true
              cash_app_pay: false
              square_gift_card: true
            created_at: '2021-01-23T15:29:12Z'
            delivery_method: EMAIL
            id: inv:0-ChC366qAfskpGrBI_1bozs9mEA3
            invoice_number: inv-455
            location_id: ES0RJRZYEC39A
            next_payment_amount_money:
              amount: 3000
              currency: USD
            order_id: a65jnS8NXbfprvGJzY9F4fQTuaB
            payment_requests:
              - automatic_payment_source: CARD_ON_FILE
                card_id: ccof:IkWfpLj4tNHMyFii3GB
                computed_amount_money:
                  amount: 1000
                  currency: USD
                due_date: '2021-01-23'
                percentage_requested: '25'
                request_type: DEPOSIT
                tipping_enabled: false
                total_completed_amount_money:
                  amount: 1000
                  currency: USD
                uid: 66c3bdfd-5090-4ff9-a8a0-c1e1a2ffa176
              - automatic_payment_source: CARD_ON_FILE
                card_id: ccof:IkWfpLj4tNHMyFii3GB
                computed_amount_money:
                  amount: 3000
                  currency: USD
                due_date: '2021-06-15'
                request_type: BALANCE
                tipping_enabled: false
                total_completed_amount_money:
                  amount: 0
                  currency: USD
                uid: 120c5e18-4f80-4f6b-b159-774cb9bf8f99
            primary_recipient:
              customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4
              email_address: Amelia.Earhart@example.com
              family_name: Earhart
              given_name: Amelia
              phone_number: 1-212-555-4240
            public_url: https://squareup.com/pay-invoice/h9sfsfTGTSnYEhISUDBhEQ
            sale_or_service_date: '2030-01-24'
            status: PARTIALLY_PAID
            store_payment_method_enabled: false
            timezone: America/Los_Angeles
            updated_at: '2021-01-23T15:29:56Z'
            version: 3
    SearchLoyaltyAccountsRequest:
      type: object
      description: A request to search for loyalty accounts.
      x-release-status: PUBLIC
      properties:
        query:
          $ref: '#/components/schemas/SearchLoyaltyAccountsRequestLoyaltyAccountQuery'
          description: The search criteria for the request.
        limit:
          type: integer
          description: >-
            The maximum number of results to include in the response. The
            default value is 30.
          minimum: 1
          maximum: 200
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to 

            this endpoint. Provide this to retrieve the next set of 

            results for the original query.


            For more information, 

            see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        limit: 10
        query:
          mappings:
            - phone_number: '+14155551234'
    SearchLoyaltyAccountsRequestLoyaltyAccountQuery:
      type: object
      description: The search criteria for the loyalty accounts.
      x-release-status: PUBLIC
      properties:
        mappings:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyAccountMapping'
          description: |-
            The set of mappings to use in the loyalty account search.  

            This cannot be combined with `customer_ids`.  

            Max: 30 mappings
          nullable: true
        customer_ids:
          type: array
          items:
            type: string
          description: |-
            The set of customer IDs to use in the loyalty account search.  

            This cannot be combined with `mappings`.  

            Max: 30 customer IDs
          nullable: true
    SearchLoyaltyAccountsResponse:
      type: object
      description: >-
        A response that includes loyalty accounts that satisfy the search
        criteria.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        loyalty_accounts:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyAccount'
          description: |-
            The loyalty accounts that met the search criteria,  
            in order of creation date.
        cursor:
          type: string
          description: >-
            The pagination cursor to use in a subsequent 

            request. If empty, this is the final response.

            For more information, 

            see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        loyalty_accounts:
          - balance: 10
            created_at: '2020-05-08T21:44:32Z'
            customer_id: Q8002FAM9V1EZ0ADB2T5609X6NET1H0
            id: 79b807d2-d786-46a9-933b-918028d7a8c5
            lifetime_points: 20
            mapping:
              created_at: '2020-05-08T21:44:32Z'
              id: 66aaab3f-da99-49ed-8b19-b87f851c844f
              phone_number: '+14155551234'
            program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
            updated_at: '2020-05-08T21:44:32Z'
    SearchLoyaltyEventsRequest:
      type: object
      description: A request to search for loyalty events.
      x-release-status: PUBLIC
      properties:
        query:
          $ref: '#/components/schemas/LoyaltyEventQuery'
          description: >-
            A set of one or more predefined query filters to apply when 

            searching for loyalty events. The endpoint performs a logical AND
            to 

            evaluate multiple filters and performs a logical OR on arrays  

            that specifies multiple field values.
        limit:
          type: integer
          description: |-
            The maximum number of results to include in the response. 
            The last page might contain fewer events. 
            The default is 30 events.
          minimum: 1
          maximum: 30
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for your original
            query.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        limit: 30
        query:
          filter:
            order_filter:
              order_id: PyATxhYLfsMqpVkcKJITPydgEYfZY
    SearchLoyaltyEventsResponse:
      type: object
      description: |-
        A response that contains loyalty events that satisfy the search 
        criteria, in order by the `created_at` date.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        events:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyEvent'
          description: The loyalty events that satisfy the search criteria.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent 

            request. If empty, this is the final response. 

            For more information, 

            see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        events:
          - accumulate_points:
              loyalty_program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
              order_id: PyATxhYLfsMqpVkcKJITPydgEYfZY
              points: 5
            created_at: '2020-05-08T22:01:30Z'
            id: c27c8465-806e-36f2-b4b3-71f5887b5ba8
            location_id: P034NEENMD09F
            loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
            source: LOYALTY_API
            type: ACCUMULATE_POINTS
          - created_at: '2020-05-08T22:01:15Z'
            id: e4a5cbc3-a4d0-3779-98e9-e578885d9430
            location_id: P034NEENMD09F
            loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
            redeem_reward:
              loyalty_program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
              order_id: PyATxhYLfsMqpVkcKJITPydgEYfZY
              reward_id: d03f79f4-815f-3500-b851-cc1e68a457f9
            source: LOYALTY_API
            type: REDEEM_REWARD
          - create_reward:
              loyalty_program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
              points: -10
              reward_id: d03f79f4-815f-3500-b851-cc1e68a457f9
            created_at: '2020-05-08T22:00:44Z'
            id: 5e127479-0b03-3671-ab1e-15faea8b7188
            loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
            source: LOYALTY_API
            type: CREATE_REWARD
    SearchLoyaltyRewardsRequest:
      type: object
      description: A request to search for loyalty rewards.
      x-release-status: PUBLIC
      properties:
        query:
          $ref: '#/components/schemas/SearchLoyaltyRewardsRequestLoyaltyRewardQuery'
          description: >-
            The search criteria for the request. 

            If empty, the endpoint retrieves all loyalty rewards in the loyalty
            program.
        limit:
          type: integer
          description: >-
            The maximum number of results to return in the response. The default
            value is 30.
          minimum: 1
          maximum: 30
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to 

            this endpoint. Provide this to retrieve the next set of 

            results for the original query.

            For more information, 

            see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        limit: 10
        query:
          loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
    SearchLoyaltyRewardsRequestLoyaltyRewardQuery:
      type: object
      description: The set of search requirements.
      x-release-status: PUBLIC
      required:
        - loyalty_account_id
      properties:
        loyalty_account_id:
          type: string
          description: >-
            The ID of the [loyalty account](entity:LoyaltyAccount) to which the
            loyalty reward belongs.
          minLength: 1
        status:
          $ref: '#/components/schemas/LoyaltyRewardStatus'
          description: >-
            The status of the loyalty reward.

            See [LoyaltyRewardStatus](#type-loyaltyrewardstatus) for possible
            values
          nullable: true
    SearchLoyaltyRewardsResponse:
      type: object
      description: >-
        A response that includes the loyalty rewards satisfying the search
        criteria.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        rewards:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyReward'
          description: |-
            The loyalty rewards that satisfy the search criteria.
            These are returned in descending order by `updated_at`.
        cursor:
          type: string
          description: |-
            The pagination cursor to be used in a subsequent 
            request. If empty, this is the final response.
      example:
        rewards:
          - created_at: '2020-05-08T22:00:44Z'
            id: d03f79f4-815f-3500-b851-cc1e68a457f9
            loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
            order_id: PyATxhYLfsMqpVkcKJITPydgEYfZY
            points: 10
            redeemed_at: '2020-05-08T22:01:17Z'
            reward_tier_id: e1b39225-9da5-43d1-a5db-782cdd8ad94f
            status: REDEEMED
            updated_at: '2020-05-08T22:01:17Z'
          - created_at: '2020-05-08T21:55:42Z'
            id: 9f18ac21-233a-31c3-be77-b45840f5a810
            loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
            points: 10
            redeemed_at: '2020-05-08T21:56:00Z'
            reward_tier_id: e1b39225-9da5-43d1-a5db-782cdd8ad94f
            status: REDEEMED
            updated_at: '2020-05-08T21:56:00Z'
          - created_at: '2020-05-01T21:49:54Z'
            id: a8f43ebe-2ad6-3001-bdd5-7d7c2da08943
            loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
            order_id: 5NB69ZNh3FbsOs1ox43bh1xrli6YY
            points: 10
            reward_tier_id: e1b39225-9da5-43d1-a5db-782cdd8ad94f
            status: DELETED
            updated_at: '2020-05-08T21:55:10Z'
          - created_at: '2020-05-01T20:20:37Z'
            id: a051254c-f840-3b45-8cf1-50bcd38ff92a
            loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
            order_id: LQQ16znvi2VIUKPVhUfJefzr1eEZY
            points: 10
            reward_tier_id: e1b39225-9da5-43d1-a5db-782cdd8ad94f
            status: ISSUED
            updated_at: '2020-05-01T20:20:40Z'
    SearchOrdersCustomerFilter:
      type: object
      description: |-
        A filter based on the order `customer_id` and any tender `customer_id`
        associated with the order. It does not filter based on the
        [FulfillmentRecipient](entity:FulfillmentRecipient) `customer_id`.
      x-release-status: BETA
      properties:
        customer_ids:
          type: array
          items:
            type: string
          description: |-
            A list of customer IDs to filter by.

            Max: 10 customer ids.
          nullable: true
    SearchOrdersDateTimeFilter:
      type: object
      description: >-
        Filter for `Order` objects based on whether their `CREATED_AT`,

        `CLOSED_AT`, or `UPDATED_AT` timestamps fall within a specified time
        range.

        You can specify the time range and which timestamp to filter for. You
        can filter

        for only one time range at a time.


        For each time range, the start time and end time are inclusive. If the
        end time

        is absent, it defaults to the time of the first request for the cursor.


        __Important:__ If you use the `DateTimeFilter` in a `SearchOrders`
        query,

        you must set the `sort_field` in [OrdersSort](entity:SearchOrdersSort)

        to the same field you filter for. For example, if you set the
        `CLOSED_AT` field

        in `DateTimeFilter`, you must set the `sort_field` in `SearchOrdersSort`
        to

        `CLOSED_AT`. Otherwise, `SearchOrders` throws an error.

        [Learn more about filtering orders by time
        range.](https://developer.squareup.com/docs/orders-api/manage-orders/search-orders#important-note-about-filtering-orders-by-time-range)
      x-release-status: PUBLIC
      properties:
        created_at:
          $ref: '#/components/schemas/TimeRange'
          description: >-
            The time range for filtering on the `created_at` timestamp. If you
            use this

            value, you must set the `sort_field` in the `OrdersSearchSort`
            object to

            `CREATED_AT`.
        updated_at:
          $ref: '#/components/schemas/TimeRange'
          description: >-
            The time range for filtering on the `updated_at` timestamp. If you
            use this

            value, you must set the `sort_field` in the `OrdersSearchSort`
            object to

            `UPDATED_AT`.
        closed_at:
          $ref: '#/components/schemas/TimeRange'
          description: >-
            The time range for filtering on the `closed_at` timestamp. If you
            use this

            value, you must set the `sort_field` in the `OrdersSearchSort`
            object to

            `CLOSED_AT`.
          nullable: true
    SearchOrdersFilter:
      type: object
      description: |-
        Filtering criteria to use for a `SearchOrders` request. Multiple filters
        are ANDed together.
      x-release-status: PUBLIC
      properties:
        state_filter:
          $ref: '#/components/schemas/SearchOrdersStateFilter'
          description: Filter by [OrderState](entity:OrderState).
          nullable: true
        date_time_filter:
          $ref: '#/components/schemas/SearchOrdersDateTimeFilter'
          description: >-
            Filter for results within a time range.


            __Important:__ If you filter for orders by time range, you must set
            `SearchOrdersSort`

            to sort by the same field.

            [Learn more about filtering orders by time
            range.](https://developer.squareup.com/docs/orders-api/manage-orders/search-orders#important-note-about-filtering-orders-by-time-range)
          nullable: true
        fulfillment_filter:
          $ref: '#/components/schemas/SearchOrdersFulfillmentFilter'
          description: Filter by the fulfillment type or state.
          nullable: true
        source_filter:
          $ref: '#/components/schemas/SearchOrdersSourceFilter'
          description: Filter by the source of the order.
          nullable: true
        customer_filter:
          $ref: '#/components/schemas/SearchOrdersCustomerFilter'
          description: Filter by customers associated with the order.
          x-release-status: BETA
          nullable: true
    SearchOrdersFulfillmentFilter:
      type: object
      description: Filter based on [order fulfillment](entity:Fulfillment) information.
      x-release-status: PUBLIC
      properties:
        fulfillment_types:
          type: array
          items:
            $ref: '#/components/schemas/FulfillmentType'
          description: >-
            A list of [fulfillment types](entity:FulfillmentType) to filter

            for. The list returns orders if any of its fulfillments match any of
            the fulfillment types

            listed in this field.

            See [FulfillmentType](#type-fulfillmenttype) for possible values
          nullable: true
        fulfillment_states:
          type: array
          items:
            $ref: '#/components/schemas/FulfillmentState'
          description: >-
            A list of [fulfillment states](entity:FulfillmentState) to filter

            for. The list returns orders if any of its fulfillments match any of
            the

            fulfillment states listed in this field.

            See [FulfillmentState](#type-fulfillmentstate) for possible values
          nullable: true
    SearchOrdersQuery:
      type: object
      description: Contains query criteria for the search.
      x-release-status: PUBLIC
      properties:
        filter:
          $ref: '#/components/schemas/SearchOrdersFilter'
          description: Criteria to filter results by.
          nullable: true
        sort:
          $ref: '#/components/schemas/SearchOrdersSort'
          description: Criteria to sort results by.
          nullable: true
    SearchOrdersRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        location_ids:
          type: array
          items:
            type: string
          description: >-
            The location IDs for the orders to query. All locations must belong
            to

            the same merchant.


            Max: 10 location IDs.
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for your
            original query.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        query:
          $ref: '#/components/schemas/SearchOrdersQuery'
          description: >-
            Query conditions used to filter or sort the results. Note that when

            retrieving additional pages using a cursor, you must use the
            original query.
        limit:
          type: integer
          description: |-
            The maximum number of results to be returned in a single page.

            Default: `500`
            Max: `1000`
        return_entries:
          type: boolean
          description: >-
            A Boolean that controls the format of the search results. If `true`,

            `SearchOrders` returns [OrderEntry](entity:OrderEntry) objects. If
            `false`, `SearchOrders`

            returns complete order objects.


            Default: `false`.
      example:
        limit: 3
        location_ids:
          - 057P5VYJ4A5X1
          - 18YC4JDH91E1H
        query:
          filter:
            date_time_filter:
              closed_at:
                end_at: '2019-03-04T21:54:45+00:00'
                start_at: '2018-03-03T20:00:00+00:00'
            state_filter:
              states:
                - COMPLETED
          sort:
            sort_field: CLOSED_AT
            sort_order: DESC
        return_entries: true
    SearchOrdersResponse:
      type: object
      description: >-
        Either the `order_entries` or `orders` field is set, depending on
        whether

        `return_entries` is set on the
        [SearchOrdersRequest](api-endpoint:Orders-SearchOrders).
      x-release-status: PUBLIC
      properties:
        order_entries:
          type: array
          items:
            $ref: '#/components/schemas/OrderEntry'
          description: >-
            A list of [OrderEntries](entity:OrderEntry) that fit the query

            conditions. The list is populated only if `return_entries` is set to
            `true` in the request.
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
          description: >-
            A list of

            [Order](entity:Order) objects that match the query conditions. The
            list is populated only if

            `return_entries` is set to `false` in the request.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If unset,

            this is the final response.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: '[Errors](entity:Error) encountered during the search.'
      example:
        cursor: '123'
        order_entries:
          - location_id: 057P5VYJ4A5X1
            order_id: CAISEM82RcpmcFBM0TfOyiHV3es
            version: 1
          - location_id: 18YC4JDH91E1H
            order_id: CAISENgvlJ6jLWAzERDzjyHVybY
          - location_id: 057P5VYJ4A5X1
            order_id: CAISEM52YcpmcWAzERDOyiWS3ty
    SearchOrdersSort:
      type: object
      description: >-
        Sorting criteria for a `SearchOrders` request. Results can only be
        sorted

        by a timestamp field.
      x-release-status: PUBLIC
      required:
        - sort_field
      properties:
        sort_field:
          $ref: '#/components/schemas/SearchOrdersSortField'
          description: >-
            The field to sort by.


            __Important:__ When using a
            [DateTimeFilter](entity:SearchOrdersFilter),

            `sort_field` must match the timestamp field that the
            `DateTimeFilter` uses to

            filter. For example, if you set your `sort_field` to `CLOSED_AT` and
            you use a

            `DateTimeFilter`, your `DateTimeFilter` must filter for orders by
            their `CLOSED_AT` date.

            If this field does not match the timestamp field in
            `DateTimeFilter`,

            `SearchOrders` returns an error.


            Default: `CREATED_AT`.

            See [SearchOrdersSortField](#type-searchorderssortfield) for
            possible values
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: >-
            The chronological order in which results are returned. Defaults to
            `DESC`.

            See [SortOrder](#type-sortorder) for possible values
          nullable: true
    SearchOrdersSortField:
      type: string
      enum:
        - CREATED_AT
        - UPDATED_AT
        - CLOSED_AT
      x-enum-elements:
        - name: CREATED_AT
          description: >-
            The time when the order was created, in RFC-3339 format. If you are
            also

            filtering for a time range in this query, you must set the
            `CREATED_AT`

            field in your `DateTimeFilter`.
        - name: UPDATED_AT
          description: >-
            The time when the order last updated, in RFC-3339 format. If you are
            also

            filtering for a time range in this query, you must set the
            `UPDATED_AT`

            field in your `DateTimeFilter`.
        - name: CLOSED_AT
          description: >-
            The time when the order was closed, in RFC-3339 format. If you use
            this

            value, you must also set a `StateFilter` with closed states. If you
            are also

            filtering for a time range in this query, you must set the
            `CLOSED_AT`

            field in your `DateTimeFilter`.
      description: Specifies which timestamp to use to sort `SearchOrder` results.
      x-release-status: PUBLIC
    SearchOrdersSourceFilter:
      type: object
      description: A filter based on order `source` information.
      x-release-status: PUBLIC
      properties:
        source_names:
          type: array
          items:
            type: string
          description: >-
            Filters by the [Source](entity:OrderSource) `name`. The filter
            returns any orders

            with a `source.name` that matches any of the listed source names.


            Max: 10 source names.
          nullable: true
    SearchOrdersStateFilter:
      type: object
      description: Filter by the current order `state`.
      x-release-status: PUBLIC
      required:
        - states
      properties:
        states:
          type: array
          items:
            $ref: '#/components/schemas/OrderState'
          description: |-
            States to filter for.
            See [OrderState](#type-orderstate) for possible values
    SearchShiftsRequest:
      type: object
      description: A request for a filtered and sorted set of `Shift` objects.
      x-release-status: PUBLIC
      properties:
        query:
          $ref: '#/components/schemas/ShiftQuery'
          description: Query filters.
        limit:
          type: integer
          description: The number of resources in a page (200 by default).
          minimum: 1
          maximum: 200
        cursor:
          type: string
          description: An opaque cursor for fetching the next page.
      example:
        limit: 100
        query:
          filter:
            workday:
              date_range:
                end_date: '2019-02-03'
                start_date: '2019-01-20'
              default_timezone: America/Los_Angeles
              match_shifts_by: START_AT
    SearchShiftsResponse:
      type: object
      description: >-
        The response to a request for `Shift` objects. The response contains

        the requested `Shift` objects and might contain a set of `Error` objects
        if

        the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        shifts:
          type: array
          items:
            $ref: '#/components/schemas/Shift'
          description: Shifts.
        cursor:
          type: string
          description: An opaque cursor for fetching the next page.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        shifts:
          - breaks:
              - break_type_id: REGS1EQR1TPZ5
                end_at: '2019-01-21T06:11:00-05:00'
                expected_duration: PT10M
                id: SJW7X6AKEJQ65
                is_paid: true
                name: Tea Break
                start_at: '2019-01-21T06:11:00-05:00'
            created_at: '2019-01-24T01:12:03Z'
            declared_cash_tip_money:
              amount: 500
              currency: USD
            employee_id: ormj0jJJZ5OZIzxrZYJI
            end_at: '2019-01-21T13:11:00-05:00'
            id: X714F3HA6D1PT
            location_id: PAA1RJZZKXBFG
            start_at: '2019-01-21T03:11:00-05:00'
            status: CLOSED
            team_member_id: ormj0jJJZ5OZIzxrZYJI
            timezone: America/New_York
            updated_at: '2019-02-07T22:21:08Z'
            version: 6
            wage:
              hourly_rate:
                amount: 1100
                currency: USD
              job_id: FzbJAtt9qEWncK1BWgVCxQ6M
              tip_eligible: true
              title: Barista
          - breaks:
              - break_type_id: WQX00VR99F53J
                end_at: '2019-01-23T14:40:00-05:00'
                expected_duration: PT10M
                id: BKS6VR7WR748A
                is_paid: true
                name: Tea Break
                start_at: '2019-01-23T14:30:00-05:00'
              - break_type_id: P6Q468ZFRN1AC
                end_at: '2019-01-22T12:44:00-05:00'
                expected_duration: PT15M
                id: BQFEZSHFZSC51
                is_paid: false
                name: Coffee Break
                start_at: '2019-01-22T12:30:00-05:00'
            created_at: '2019-01-23T23:32:45Z'
            declared_cash_tip_money:
              amount: 0
              currency: USD
            employee_id: 33fJchumvVdJwxV0H6L9
            end_at: '2019-01-22T13:02:00-05:00'
            id: GDHYBZYWK0P2V
            location_id: PAA1RJZZKXBFG
            start_at: '2019-01-22T12:02:00-05:00'
            status: CLOSED
            team_member_id: 33fJchumvVdJwxV0H6L9
            timezone: America/New_York
            updated_at: '2019-01-24T00:56:25Z'
            version: 16
            wage:
              hourly_rate:
                amount: 1600
                currency: USD
              job_id: gcbz15vKGnMKmaWJJ152kjim
              tip_eligible: true
              title: Cook
    SearchSubscriptionsFilter:
      type: object
      description: >-
        Represents a set of query expressions (filters) to narrow the scope of
        targeted subscriptions returned by 

        the
        [SearchSubscriptions](api-endpoint:Subscriptions-SearchSubscriptions)
        endpoint.
      x-release-status: PUBLIC
      properties:
        customer_ids:
          type: array
          items:
            type: string
          description: >-
            A filter to select subscriptions based on the subscribing customer
            IDs.
          nullable: true
        location_ids:
          type: array
          items:
            type: string
          description: A filter to select subscriptions based on the location.
          nullable: true
        source_names:
          type: array
          items:
            type: string
          description: A filter to select subscriptions based on the source application.
          x-release-status: BETA
          nullable: true
    SearchSubscriptionsQuery:
      type: object
      description: >-
        Represents a query, consisting of specified query expressions, used to
        search for subscriptions.
      x-release-status: PUBLIC
      properties:
        filter:
          $ref: '#/components/schemas/SearchSubscriptionsFilter'
          description: A list of query expressions.
          nullable: true
    SearchSubscriptionsRequest:
      type: object
      description: >-
        Defines input parameters in a request to the 

        [SearchSubscriptions](api-endpoint:Subscriptions-SearchSubscriptions)
        endpoint.
      x-release-status: PUBLIC
      properties:
        cursor:
          type: string
          description: >-
            When the total number of resulting subscriptions exceeds the limit
            of a paged response, 

            specify the cursor returned from a preceding response here to fetch
            the next set of results.

            If the cursor is unset, the response contains the last page of the
            results.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
        limit:
          type: integer
          description: |-
            The upper limit on the number of subscriptions to return
            in a paged response.
          minimum: 1
        query:
          $ref: '#/components/schemas/SearchSubscriptionsQuery'
          description: >-
            A subscription query consisting of specified filtering conditions.


            If this `query` field is unspecified, the `SearchSubscriptions` call
            will return all subscriptions.
        include:
          type: array
          items:
            type: string
          description: >-
            An option to include related information in the response. 


            The supported values are: 


            - `actions`: to include scheduled actions on the targeted
            subscriptions.
          x-release-status: BETA
      example:
        query:
          filter:
            customer_ids:
              - CHFGVKYY8RSV93M5KCYTG4PN0G
            location_ids:
              - S8GWD5R9QB376
            source_names:
              - My App
    SearchSubscriptionsResponse:
      type: object
      description: >-
        Defines output parameters in a response from the

        [SearchSubscriptions](api-endpoint:Subscriptions-SearchSubscriptions)
        endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered during the request.
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
          description: The subscriptions matching the specified query expressions.
        cursor:
          type: string
          description: >-
            When the total number of resulting subscription exceeds the limit of
            a paged response, 

            the response includes a cursor for you to use in a subsequent
            request to fetch the next set of results.

            If the cursor is unset, the response contains the last page of the
            results.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
      example:
        subscriptions:
          - canceled_date: '2021-10-30'
            card_id: ccof:mueUsvgajChmjEbp4GB
            charged_through_date: '2021-11-20'
            created_at: '2021-10-20T21:53:10Z'
            customer_id: CHFGVKYY8RSV93M5KCYTG4PN0G
            id: de86fc96-8664-474b-af1a-abbe59cacf0e
            location_id: S8GWD5R9QB376
            paid_until_date: '2021-11-20'
            plan_variation_id: L3TJVDHVBEQEGQDEZL2JJM7R
            source:
              name: My Application
            start_date: '2021-10-20'
            status: CANCELED
            timezone: UTC
          - charged_through_date: '2022-08-19'
            created_at: '2022-01-19T21:53:10Z'
            customer_id: CHFGVKYY8RSV93M5KCYTG4PN0G
            id: 56214fb2-cc85-47a1-93bc-44f3766bb56f
            invoice_ids:
              - grebK0Q_l8H4fqoMMVvt-Q
              - rcX_i3sNmHTGKhI4W2mceA
            location_id: S8GWD5R9QB376
            plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
            price_override_money:
              amount: 1000
              currency: USD
            source:
              name: My Application
            start_date: '2022-01-19'
            status: PAUSED
            tax_percentage: '5'
            timezone: America/Los_Angeles
            version: 2
          - card_id: ccof:qy5x8hHGYsgLrp4Q4GB
            created_at: '2023-06-20T21:53:10Z'
            customer_id: CHFGVKYY8RSV93M5KCYTG4PN0G
            id: 56214fb2-cc85-47a1-93bc-44f3766bb56f
            location_id: S8GWD5R9QB376
            phases:
              - order_template_id: U2NaowWxzXwpsZU697x7ZHOAnCNZY
                ordinal: 0
                plan_phase_uid: X2Q2AONPB3RB64Y27S25QCZP
                uid: 873451e0-745b-4e87-ab0b-c574933fe616
            plan_variation_id: 6JHXF3B2CW3YKHDV4XEM674H
            source:
              name: My Application
            start_date: '2023-06-20'
            status: ACTIVE
            timezone: America/Los_Angeles
            version: 1
    SearchTeamMembersFilter:
      type: object
      description: >-
        Represents a filter used in a search for `TeamMember` objects. `AND`
        logic is applied

        between the individual fields, and `OR` logic is applied within
        list-based fields.

        For example, setting this filter value:

        ```

        filter = (locations_ids = ["A", "B"], status = ACTIVE)

        ```

        returns only active team members assigned to either location "A" or "B".
      x-release-status: PUBLIC
      properties:
        location_ids:
          type: array
          items:
            type: string
          description: >-
            When present, filters by team members assigned to the specified
            locations.

            When empty, includes team members assigned to any location.
          nullable: true
        status:
          $ref: '#/components/schemas/TeamMemberStatus'
          description: |-
            When present, filters by team members who match the given status.
            When empty, includes team members of all statuses.
            See [TeamMemberStatus](#type-teammemberstatus) for possible values
          nullable: true
        is_owner:
          type: boolean
          description: >-
            When present and set to true, returns the team member who is the
            owner of the Square account.
          nullable: true
    SearchTeamMembersQuery:
      type: object
      description: Represents the parameters in a search for `TeamMember` objects.
      x-release-status: PUBLIC
      properties:
        filter:
          $ref: '#/components/schemas/SearchTeamMembersFilter'
          description: The options to filter by.
          nullable: true
    SearchTeamMembersRequest:
      type: object
      description: Represents a search request for a filtered list of `TeamMember` objects.
      x-release-status: PUBLIC
      properties:
        query:
          $ref: '#/components/schemas/SearchTeamMembersQuery'
          description: The query parameters.
        limit:
          type: integer
          description: >-
            The maximum number of `TeamMember` objects in a page (100 by
            default).
          minimum: 1
          maximum: 200
        cursor:
          type: string
          description: >-
            The opaque cursor for fetching the next page. For more information,
            see

            [pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
      example:
        limit: 10
        query:
          filter:
            location_ids:
              - 0G5P3VGACMMQZ
            status: ACTIVE
    SearchTeamMembersResponse:
      type: object
      description: >-
        Represents a response from a search request containing a filtered list
        of `TeamMember` objects.
      x-release-status: PUBLIC
      properties:
        team_members:
          type: array
          items:
            $ref: '#/components/schemas/TeamMember'
          description: The filtered list of `TeamMember` objects.
        cursor:
          type: string
          description: >-
            The opaque cursor for fetching the next page. For more information,
            see

            [pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: The errors that occurred during the request.
      example:
        cursor: N:9UglUjOXQ13-hMFypCft
        team_members:
          - assigned_locations:
              assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
            created_at: '2019-07-10T17:26:48Z'
            email_address: johnny_cash@squareup.com
            family_name: Cash
            given_name: Johnny
            id: '-3oZQKPKVk6gUXU_V5Qa'
            is_owner: false
            reference_id: '12345678'
            status: ACTIVE
            updated_at: '2020-04-28T21:49:28Z'
            wage_setting:
              created_at: '2021-06-11T22:55:45Z'
              is_overtime_exempt: true
              job_assignments:
                - annual_rate:
                    amount: 3000000
                    currency: USD
                  hourly_rate:
                    amount: 1443
                    currency: USD
                  job_id: FjS8x95cqHiMenw4f1NAUH4P
                  job_title: Manager
                  pay_type: SALARY
                  weekly_hours: 40
                - hourly_rate:
                    amount: 2000
                    currency: USD
                  job_id: VDNpRv8da51NU8qZFC5zDWpF
                  job_title: Cashier
                  pay_type: HOURLY
              team_member_id: '-3oZQKPKVk6gUXU_V5Qa'
              updated_at: '2021-06-11T22:55:45Z'
              version: 1
          - assigned_locations:
              assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
            created_at: '2020-03-24T18:14:01Z'
            family_name: Smith
            given_name: Lombard
            id: 1AVJj0DjkzbmbJw5r4KK
            is_owner: false
            phone_number: '+14155552671'
            reference_id: abcded
            status: ACTIVE
            updated_at: '2020-06-09T17:38:05Z'
            wage_setting:
              created_at: '2020-03-24T18:14:01Z'
              is_overtime_exempt: true
              job_assignments:
                - hourly_rate:
                    amount: 2400
                    currency: USD
                  job_id: VDNpRv8da51NU8qZFC5zDWpF
                  job_title: Cashier
                  pay_type: HOURLY
              team_member_id: 1AVJj0DjkzbmbJw5r4KK
              updated_at: '2020-06-09T17:38:05Z'
              version: 2
          - assigned_locations:
              assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
            created_at: '2020-03-24T01:09:25Z'
            family_name: Sway
            given_name: Monica
            id: 2JCmiJol_KKFs9z2Evim
            is_owner: false
            status: ACTIVE
            updated_at: '2020-03-24T01:11:25Z'
            wage_setting:
              created_at: '2020-03-24T01:09:25Z'
              is_overtime_exempt: true
              job_assignments:
                - hourly_rate:
                    amount: 2400
                    currency: USD
                  job_id: VDNpRv8da51NU8qZFC5zDWpF
                  job_title: Cashier
                  pay_type: HOURLY
              team_member_id: 2JCmiJol_KKFs9z2Evim
              updated_at: '2020-03-24T01:09:25Z'
              version: 1
          - assigned_locations:
              assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
            created_at: '2020-03-24T01:09:23Z'
            family_name: Ipsum
            given_name: Elton
            id: 4uXcJQSLtbk3F0UQHFNQ
            is_owner: false
            status: ACTIVE
            updated_at: '2020-03-24T01:15:23Z'
          - assigned_locations:
              assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
            created_at: '2020-03-24T01:09:23Z'
            family_name: Lo
            given_name: Steven
            id: 5CoUpyrw1YwGWcRd-eDL
            is_owner: false
            status: ACTIVE
            updated_at: '2020-03-24T01:19:23Z'
          - assigned_locations:
              assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
            created_at: '2020-03-24T18:14:03Z'
            family_name: Steward
            given_name: Patrick
            id: 5MRPTTp8MMBLVSmzrGha
            is_owner: false
            phone_number: '+14155552671'
            status: ACTIVE
            updated_at: '2020-03-24T18:18:03Z'
            wage_setting:
              created_at: '2020-03-24T18:14:03Z'
              is_overtime_exempt: true
              job_assignments:
                - hourly_rate:
                    amount: 2000
                    currency: USD
                  job_id: VDNpRv8da51NU8qZFC5zDWpF
                  job_title: Cashier
                  pay_type: HOURLY
              team_member_id: 5MRPTTp8MMBLVSmzrGha
              updated_at: '2020-03-24T18:14:03Z'
              version: 1
          - assigned_locations:
              assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
            created_at: '2020-03-24T01:09:25Z'
            family_name: Manny
            given_name: Ivy
            id: 7F5ZxsfRnkexhu1PTbfh
            is_owner: false
            status: ACTIVE
            updated_at: '2020-03-24T01:09:25Z'
          - assigned_locations:
              assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
            created_at: '2020-03-24T18:14:02Z'
            email_address: john_smith@example.com
            family_name: Smith
            given_name: John
            id: 808X9HR72yKvVaigQXf4
            is_owner: false
            phone_number: '+14155552671'
            status: ACTIVE
            updated_at: '2020-03-24T18:14:02Z'
          - assigned_locations:
              assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
            created_at: '2020-03-24T18:14:00Z'
            email_address: r_wen@example.com
            family_name: Wen
            given_name: Robert
            id: 9MVDVoY4hazkWKGo_OuZ
            is_owner: false
            phone_number: '+14155552671'
            status: ACTIVE
            updated_at: '2020-03-24T18:14:00Z'
          - assigned_locations:
              assignment_type: ALL_CURRENT_AND_FUTURE_LOCATIONS
            created_at: '2020-03-24T18:14:00Z'
            email_address: asimpson@example.com
            family_name: Simpson
            given_name: Ashley
            id: 9UglUjOXQ13-hMFypCft
            is_owner: false
            phone_number: '+14155552671'
            status: ACTIVE
            updated_at: '2020-03-24T18:18:00Z'
            wage_setting:
              created_at: '2020-03-24T18:14:00Z'
              is_overtime_exempt: true
              job_assignments:
                - hourly_rate:
                    amount: 2000
                    currency: USD
                  job_id: VDNpRv8da51NU8qZFC5zDWpF
                  job_title: Cashier
                  pay_type: HOURLY
              team_member_id: 9UglUjOXQ13-hMFypCft
              updated_at: '2020-03-24T18:14:03Z'
              version: 1
    SearchTerminalActionsRequest:
      type: object
      x-release-status: BETA
      properties:
        query:
          $ref: '#/components/schemas/TerminalActionQuery'
          description: >-
            Queries terminal actions based on given conditions and sort order.

            Leaving this unset will return all actions with the default sort
            order.
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for the original
            query.

            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more

            information.
        limit:
          type: integer
          description: Limit the number of results returned for a single request.
          minimum: 1
          maximum: 100
      example:
        limit: 2
        query:
          filter:
            created_at:
              start_at: '2022-04-01T00:00:00.000Z'
          sort:
            sort_order: DESC
    SearchTerminalActionsResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        action:
          type: array
          items:
            $ref: '#/components/schemas/TerminalAction'
          description: The requested search result of `TerminalAction`s.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,

            this is the final response.


            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more

            information.
      example:
        action:
          - app_id: APP_ID
            created_at: '2022-04-08T15:14:04.895Z'
            deadline_duration: PT5M
            device_id: DEVICE_ID
            id: termapia:oBGWlAats8xWCiCE
            location_id: LOCATION_ID
            save_card_options:
              customer_id: CUSTOMER_ID
              reference_id: user-id-1
            status: IN_PROGRESS
            type: SAVE_CARD
            updated_at: '2022-04-08T15:14:05.446Z'
          - app_id: APP_ID
            created_at: '2022-04-08T15:14:01.210Z'
            deadline_duration: PT5M
            device_id: DEVICE_ID
            id: termapia:K2NY2YSSml3lTiCE
            location_id: LOCATION_ID
            save_card_options:
              card_id: ccof:CARD_ID
              customer_id: CUSTOMER_ID
              reference_id: user-id-1
            status: COMPLETED
            type: SAVE_CARD
            updated_at: '2022-04-08T15:14:09.861Z'
        cursor: CURSOR
    SearchTerminalCheckoutsRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        query:
          $ref: '#/components/schemas/TerminalCheckoutQuery'
          description: >-
            Queries Terminal checkouts based on given conditions and the sort
            order.

            Leaving these unset returns all checkouts with the default sort
            order.
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
        limit:
          type: integer
          description: Limits the number of results returned for a single request.
          minimum: 1
          maximum: 100
      example:
        limit: 2
        query:
          filter:
            status: COMPLETED
    SearchTerminalCheckoutsResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        checkouts:
          type: array
          items:
            $ref: '#/components/schemas/TerminalCheckout'
          description: The requested search result of `TerminalCheckout` objects.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,

            this is the final response.


            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
      example:
        checkouts:
          - amount_money:
              amount: 2610
              currency: USD
            app_id: APP_ID
            created_at: '2020-03-31T18:13:15.921Z'
            deadline_duration: PT5M
            device_options:
              device_id: dbb5d83a-7838-11ea-bc55-0242ac130003
              skip_receipt_screen: false
              tip_settings:
                allow_tipping: false
            id: tsQPvzwBpMqqO
            note: A brief note
            payment_ids:
              - rXnhZzywrEk4vR6pw76fPZfgvaB
            reference_id: id14467
            status: COMPLETED
            updated_at: '2020-03-31T18:13:52.725Z'
          - amount_money:
              amount: 2610
              currency: USD
            app_id: APP_ID
            created_at: '2020-03-31T18:08:31.882Z'
            deadline_duration: PT5M
            device_options:
              device_id: dbb5d83a-7838-11ea-bc55-0242ac130003
              skip_receipt_screen: true
              tip_settings:
                allow_tipping: false
            id: XlOPTgcEhrbqO
            note: A brief note
            payment_ids:
              - VYBF861PaoKPP7Pih0TlbZiNvaB
            reference_id: id41623
            status: COMPLETED
            updated_at: '2020-03-31T18:08:41.635Z'
        cursor: RiTJqBoTuXlbLmmrPvEkX9iG7XnQ4W4RjGnH
    SearchTerminalRefundsRequest:
      type: object
      x-release-status: PUBLIC
      properties:
        query:
          $ref: '#/components/schemas/TerminalRefundQuery'
          description: >-
            Queries the Terminal refunds based on given conditions and the sort
            order. Calling

            `SearchTerminalRefunds` without an explicit query parameter returns
            all available

            refunds with the default sort order.
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.
        limit:
          type: integer
          description: Limits the number of results returned for a single request.
          minimum: 1
          maximum: 100
      example:
        limit: 1
        query:
          filter:
            status: COMPLETED
    SearchTerminalRefundsResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/TerminalRefund'
          description: The requested search result of `TerminalRefund` objects.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If empty,

            this is the final response.


            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
      example:
        refunds:
          - amount_money:
              amount: 111
              currency: CAD
            app_id: sandbox-sq0idb-c2OuYt13YaCAeJq_2cd8OQ
            card:
              bin: '411111'
              card_brand: INTERAC
              card_type: CREDIT
              exp_month: 1
              exp_year: 2022
              fingerprint: >-
                sq-1-B1fP9MNNmZgVVaPKRND6oDKYbz25S2cTvg9Mzwg3RMTK1zT1PiGRT-AE3nTA8vSmmw
              last_4: '1111'
            created_at: '2020-09-29T15:21:46.771Z'
            deadline_duration: PT5M
            device_id: f72dfb8e-4d65-4e56-aade-ec3fb8d33291
            id: 009DP5HD-5O5OvgkcNUhl7JBuINflcjKqUzXZY
            location_id: 76C9W6K8CNNQ5
            order_id: kcuKDKreRaI4gF4TjmEgZjHk8Z7YY
            payment_id: 5O5OvgkcNUhl7JBuINflcjKqUzXZY
            reason: Returning item
            refund_id: >-
              5O5OvgkcNUhl7JBuINflcjKqUzXZY_43Q4iGp7sNeATiWrUruA1EYeMRUXaddXXlDDJ1EQLvb
            status: COMPLETED
            updated_at: '2020-09-29T15:21:48.675Z'
    SearchVendorsRequest:
      type: object
      description: >-
        Represents an input into a call to
        [SearchVendors](api-endpoint:Vendors-SearchVendors).
      x-release-status: BETA
      properties:
        filter:
          $ref: '#/components/schemas/SearchVendorsRequestFilter'
          description: Specifies a filter used to search for vendors.
        sort:
          $ref: '#/components/schemas/SearchVendorsRequestSort'
          description: Specifies a sorter used to sort the returned vendors.
        cursor:
          type: string
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for the original
            query.


            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
      example:
        query:
          filter:
            name:
              - Joe's Fresh Seafood
              - Hannah's Bakery
            status:
              - ACTIVE
          sort:
            field: CREATED_AT
            order: ASC
    SearchVendorsRequestFilter:
      type: object
      description: Defines supported query expressions to search for vendors by.
      x-release-status: BETA
      properties:
        name:
          type: array
          items:
            type: string
          description: The names of the [Vendor](entity:Vendor) objects to retrieve.
          nullable: true
        status:
          type: array
          items:
            $ref: '#/components/schemas/VendorStatus'
          description: |-
            The statuses of the [Vendor](entity:Vendor) objects to retrieve.
            See [VendorStatus](#type-vendorstatus) for possible values
          nullable: true
    SearchVendorsRequestSort:
      type: object
      description: >-
        Defines a sorter used to sort results from
        [SearchVendors](api-endpoint:Vendors-SearchVendors).
      x-release-status: BETA
      properties:
        field:
          $ref: '#/components/schemas/SearchVendorsRequestSortField'
          description: |-
            Specifies the sort key to sort the returned vendors.
            See [Field](#type-field) for possible values
          nullable: true
        order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            Specifies the sort order for the returned vendors.
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
    SearchVendorsRequestSortField:
      type: string
      enum:
        - NAME
        - CREATED_AT
      x-enum-elements:
        - name: NAME
          description: >-
            To sort the result by the name of the [Vendor](entity:Vendor)
            objects.
        - name: CREATED_AT
          description: >-
            To sort the result by the creation time of the
            [Vendor](entity:Vendor) objects.
      description: The field to sort the returned [Vendor](entity:Vendor) objects by.
      x-release-status: BETA
    SearchVendorsResponse:
      type: object
      description: >-
        Represents an output from a call to
        [SearchVendors](api-endpoint:Vendors-SearchVendors).
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered when the request fails.
        vendors:
          type: array
          items:
            $ref: '#/components/schemas/Vendor'
          description: >-
            The [Vendor](entity:Vendor) objects matching the specified search
            filter.
        cursor:
          type: string
          description: >-
            The pagination cursor to be used in a subsequent request. If unset,

            this is the final response.


            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
      example:
        vendors:
          - account_number: '4025391'
            address:
              address_line_1: 505 Electric Ave
              address_line_2: Suite 600
              administrative_district_level_1: NY
              country: US
              locality: New York
              postal_code: '10003'
            contacts:
              - email_address: joe@joesfreshseafood.com
                id: INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A
                name: Joe Burrow
                phone_number: 1-212-555-4250
            created_at: '2022-03-16T10:21:54.859Z'
            id: INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4
            name: Joe's Fresh Seafood
            note: a vendor
            status: ACTIVE
            updated_at: '2022-03-16T10:21:54.859Z'
            version: 1
    SegmentFilter:
      type: object
      description: A query filter to search for buyer-accessible appointment segments by.
      x-release-status: PUBLIC
      required:
        - service_variation_id
      properties:
        service_variation_id:
          type: string
          description: >-
            The ID of the [CatalogItemVariation](entity:CatalogItemVariation)
            object representing the service booked in this segment.
          minLength: 1
          maxLength: 36
        team_member_id_filter:
          $ref: '#/components/schemas/FilterValue'
          description: >-
            A query filter to search for buyer-accessible appointment segments
            with service-providing team members matching the specified list of
            team member IDs.  Supported query expressions are

            - `ANY`: return the appointment segments with team members whose IDs
            match any member in this list.

            - `NONE`: return the appointment segments with team members whose
            IDs are not in this list.

            - `ALL`: not supported.


            When no expression is specified, any service-providing team member
            is eligible to fulfill the Booking.
          nullable: true
    SelectOption:
      type: object
      x-release-status: BETA
      required:
        - reference_id
        - title
      properties:
        reference_id:
          type: string
          description: The reference id for the option.
          minLength: 1
          maxLength: 40
        title:
          type: string
          description: The title text that displays in the select option button.
          minLength: 1
          maxLength: 250
    SelectOptions:
      type: object
      x-release-status: BETA
      required:
        - title
        - body
        - options
      properties:
        title:
          type: string
          description: The title text to display in the select flow on the Terminal.
          minLength: 1
          maxLength: 250
        body:
          type: string
          description: The body text to display in the select flow on the Terminal.
          minLength: 1
          maxLength: 10000
        options:
          type: array
          items:
            $ref: '#/components/schemas/SelectOption'
          description: >-
            Represents the buttons/options that should be displayed in the
            select flow on the Terminal.
        selected_option:
          $ref: '#/components/schemas/SelectOption'
          description: The buyers selected option.
          readOnly: true
    Shift:
      type: object
      description: >-
        A record of the hourly rate, start, and end times for a single work
        shift

        for an employee. This might include a record of the start and end times
        for breaks

        taken during the shift.
      x-release-status: PUBLIC
      required:
        - location_id
        - start_at
      properties:
        id:
          type: string
          description: The UUID for this object.
          maxLength: 255
        employee_id:
          type: string
          description: >-
            The ID of the employee this shift belongs to. DEPRECATED at version
            2020-08-26. Use `team_member_id` instead.
          x-release-status: DEPRECATED
          nullable: true
        location_id:
          type: string
          description: >-
            The ID of the location this shift occurred at. The location should
            be based on

            where the employee clocked in.
          minLength: 1
        timezone:
          type: string
          description: >-
            The read-only convenience value that is calculated from the location
            based

            on the `location_id`. Format: the IANA timezone database identifier
            for the

            location timezone.
          nullable: true
        start_at:
          type: string
          description: >-
            RFC 3339; shifted to the location timezone + offset. Precision up to
            the

            minute is respected; seconds are truncated.
          minLength: 1
        end_at:
          type: string
          description: >-
            RFC 3339; shifted to the timezone + offset. Precision up to the
            minute is

            respected; seconds are truncated.
          nullable: true
        wage:
          $ref: '#/components/schemas/ShiftWage'
          description: >-
            Job and pay related information. If the wage is not set on create,
            it defaults to a wage

            of zero. If the title is not set on create, it defaults to the name
            of the role the employee

            is assigned to, if any.
          nullable: true
        breaks:
          type: array
          items:
            $ref: '#/components/schemas/Break'
          description: >-
            A list of all the paid or unpaid breaks that were taken during this
            shift.
          nullable: true
        status:
          $ref: '#/components/schemas/ShiftStatus'
          description: |-
            Describes the working state of the current `Shift`.
            See [ShiftStatus](#type-shiftstatus) for possible values
          nullable: true
        version:
          type: integer
          description: >-
            Used for resolving concurrency issues. The request fails if the
            version

            provided does not match the server version at the time of the
            request. If not provided,

            Square executes a blind write; potentially overwriting data from
            another

            write.
        created_at:
          type: string
          description: A read-only timestamp in RFC 3339 format; presented in UTC.
          readOnly: true
        updated_at:
          type: string
          description: A read-only timestamp in RFC 3339 format; presented in UTC.
          readOnly: true
        team_member_id:
          type: string
          description: >-
            The ID of the team member this shift belongs to. Replaced
            `employee_id` at version "2020-08-26".
          nullable: true
        declared_cash_tip_money:
          $ref: '#/components/schemas/Money'
          description: The tips declared by the team member for the shift.
          nullable: true
    ShiftFilter:
      type: object
      description: |-
        Defines a filter used in a search for `Shift` records. `AND` logic is
        used by Square's servers to apply each filter property specified.
      x-release-status: PUBLIC
      properties:
        location_ids:
          type: array
          items:
            type: string
          description: Fetch shifts for the specified location.
          nullable: true
        employee_ids:
          type: array
          items:
            type: string
          description: >-
            Fetch shifts for the specified employees. DEPRECATED at version
            2020-08-26. Use `team_member_ids` instead.
          x-release-status: DEPRECATED
          nullable: true
        status:
          $ref: '#/components/schemas/ShiftFilterStatus'
          description: |-
            Fetch a `Shift` instance by `Shift.status`.
            See [ShiftFilterStatus](#type-shiftfilterstatus) for possible values
          nullable: true
        start:
          $ref: '#/components/schemas/TimeRange'
          description: Fetch `Shift` instances that start in the time range - Inclusive.
          nullable: true
        end:
          $ref: '#/components/schemas/TimeRange'
          description: Fetch the `Shift` instances that end in the time range - Inclusive.
          nullable: true
        workday:
          $ref: '#/components/schemas/ShiftWorkday'
          description: Fetch the `Shift` instances based on the workday date range.
          nullable: true
        team_member_ids:
          type: array
          items:
            type: string
          description: >-
            Fetch shifts for the specified team members. Replaced `employee_ids`
            at version "2020-08-26".
          nullable: true
    ShiftFilterStatus:
      type: string
      enum:
        - OPEN
        - CLOSED
      x-enum-elements:
        - name: OPEN
          description: Shifts that have been started and not ended.
        - name: CLOSED
          description: Shifts that have been started and ended.
      description: Specifies the `status` of `Shift` records to be returned.
      x-release-status: PUBLIC
    ShiftQuery:
      type: object
      description: >-
        The parameters of a `Shift` search query, which includes filter and sort
        options.
      x-release-status: PUBLIC
      properties:
        filter:
          $ref: '#/components/schemas/ShiftFilter'
          description: Query filter options.
          nullable: true
        sort:
          $ref: '#/components/schemas/ShiftSort'
          description: Sort order details.
          nullable: true
    ShiftSort:
      type: object
      description: Sets the sort order of search results.
      x-release-status: PUBLIC
      properties:
        field:
          $ref: '#/components/schemas/ShiftSortField'
          description: |-
            The field to sort on.
            See [ShiftSortField](#type-shiftsortfield) for possible values
          nullable: true
        order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            The order in which results are returned. Defaults to DESC.
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
    ShiftSortField:
      type: string
      enum:
        - START_AT
        - END_AT
        - CREATED_AT
        - UPDATED_AT
      x-enum-elements:
        - name: START_AT
          description: The start date/time of a `Shift`
        - name: END_AT
          description: The end date/time of a `Shift`
        - name: CREATED_AT
          description: The date/time that a `Shift` is created
        - name: UPDATED_AT
          description: The most recent date/time that a `Shift` is updated
      description: Enumerates the `Shift` fields to sort on.
      x-release-status: PUBLIC
    ShiftStatus:
      type: string
      enum:
        - OPEN
        - CLOSED
      x-enum-elements:
        - name: OPEN
          description: Employee started a work shift and the shift is not complete
        - name: CLOSED
          description: Employee started and ended a work shift.
      description: Enumerates the possible status of a `Shift`.
      x-release-status: PUBLIC
    ShiftWage:
      type: object
      description: The hourly wage rate used to compensate an employee for this shift.
      x-release-status: PUBLIC
      properties:
        title:
          type: string
          description: The name of the job performed during this shift.
          nullable: true
        hourly_rate:
          $ref: '#/components/schemas/Money'
          description: |-
            Can be a custom-set hourly wage or the calculated effective hourly
            wage based on the annual wage and hours worked per week.
          nullable: true
        job_id:
          type: string
          description: >-
            The id of the job performed during this shift. Square

            labor-reporting UIs might group shifts together by id. This cannot
            be used to retrieve the job.
          readOnly: true
        tip_eligible:
          type: boolean
          description: Whether team members are eligible for tips when working this job.
          nullable: true
    ShiftWorkday:
      type: object
      description: |-
        A `Shift` search query filter parameter that sets a range of days that
        a `Shift` must start or end in before passing the filter condition.
      x-release-status: PUBLIC
      properties:
        date_range:
          $ref: '#/components/schemas/DateRange'
          description: Dates for fetching the shifts.
          nullable: true
        match_shifts_by:
          $ref: '#/components/schemas/ShiftWorkdayMatcher'
          description: >-
            The strategy on which the dates are applied.

            See [ShiftWorkdayMatcher](#type-shiftworkdaymatcher) for possible
            values
          nullable: true
        default_timezone:
          type: string
          description: >-
            Location-specific timezones convert workdays to datetime filters.

            Every location included in the query must have a timezone or this
            field

            must be provided as a fallback. Format: the IANA timezone database

            identifier for the relevant timezone.
          nullable: true
    ShiftWorkdayMatcher:
      type: string
      enum:
        - START_AT
        - END_AT
        - INTERSECTION
      x-enum-elements:
        - name: START_AT
          description: All shifts that start on or after the specified workday
        - name: END_AT
          description: All shifts that end on or before the specified workday
        - name: INTERSECTION
          description: All shifts that start between the start and end workdays (inclusive)
      description: Defines the logic used to apply a workday filter.
      x-release-status: PUBLIC
    ShippingFee:
      type: object
      x-release-status: PUBLIC
      required:
        - charge
      properties:
        name:
          type: string
          description: The name for the shipping fee.
          nullable: true
        charge:
          $ref: '#/components/schemas/Money'
          description: The amount and currency for the shipping fee.
    SignatureImage:
      type: object
      x-release-status: BETA
      properties:
        image_type:
          type: string
          description: |-
            The mime/type of the image data.
            Use `image/png;base64` for png.
          readOnly: true
        data:
          type: string
          description: The base64 representation of the image.
          readOnly: true
    SignatureOptions:
      type: object
      x-release-status: BETA
      required:
        - title
        - body
      properties:
        title:
          type: string
          description: >-
            The title text to display in the signature capture flow on the
            Terminal.
          minLength: 1
          maxLength: 250
        body:
          type: string
          description: >-
            The body text to display in the signature capture flow on the
            Terminal.
          minLength: 1
          maxLength: 10000
        signature:
          type: array
          items:
            $ref: '#/components/schemas/SignatureImage'
          description: An image representation of the collected signature.
          readOnly: true
    Site:
      type: object
      description: >-
        Represents a Square Online site, which is an online store for a Square
        seller.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: The Square-assigned ID of the site.
          maxLength: 32
          readOnly: true
        site_title:
          type: string
          description: The title of the site.
          nullable: true
        domain:
          type: string
          description: >-
            The domain of the site (without the protocol). For example,
            `mysite1.square.site`.
          nullable: true
        is_published:
          type: boolean
          description: Indicates whether the site is published.
          nullable: true
        created_at:
          type: string
          description: The timestamp of when the site was created, in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: The timestamp of when the site was last updated, in RFC 3339 format.
          readOnly: true
    Snippet:
      type: object
      description: >-
        Represents the snippet that is added to a Square Online site. The
        snippet code is injected into the `head` element of all pages on the
        site, except for checkout pages.
      x-release-status: PUBLIC
      required:
        - content
      properties:
        id:
          type: string
          description: The Square-assigned ID for the snippet.
          maxLength: 48
          readOnly: true
        site_id:
          type: string
          description: The ID of the site that contains the snippet.
          readOnly: true
        content:
          type: string
          description: The snippet code, which can contain valid HTML, JavaScript, or both.
          minLength: 1
          maxLength: 65535
        created_at:
          type: string
          description: >-
            The timestamp of when the snippet was initially added to the site,
            in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp of when the snippet was last updated on the site, in
            RFC 3339 format.
          readOnly: true
    SnippetResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        snippet:
          $ref: '#/components/schemas/Snippet'
          description: The snippet.
    SortOrder:
      type: string
      enum:
        - DESC
        - ASC
      x-enum-elements:
        - name: DESC
          description: >-
            The results are returned in descending (e.g., newest-first or Z-A)
            order.
        - name: ASC
          description: >-
            The results are returned in ascending (e.g., oldest-first or A-Z)
            order.
      description: >-
        The order (e.g., chronological or alphabetical) in which results from a
        request are returned.
      x-release-status: PUBLIC
    SourceApplication:
      type: object
      description: Represents information about the application used to generate a change.
      x-release-status: PUBLIC
      properties:
        product:
          $ref: '#/components/schemas/Product'
          description: |-
            __Read only__ The [product](entity:Product) type of the application.
            See [Product](#type-product) for possible values
          nullable: true
        application_id:
          type: string
          description: >-
            __Read only__ The Square-assigned ID of the application. This field
            is used only if the

            [product](entity:Product) type is `EXTERNAL_API`.
          nullable: true
        name:
          type: string
          description: >-
            __Read only__ The display name of the application

            (for example, `"Custom Application"` or `"Square POS 4.74 for
            Android"`).
          nullable: true
    SquareAccountDetails:
      type: object
      description: Additional details about Square Account payments.
      x-release-status: PUBLIC
      properties:
        payment_source_token:
          type: string
          description: Unique identifier for the payment source used for this payment.
          maxLength: 255
          nullable: true
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
          nullable: true
    StandardUnitDescription:
      type: object
      description: Contains the name and abbreviation for standard measurement unit.
      x-release-status: PUBLIC
      properties:
        unit:
          $ref: '#/components/schemas/MeasurementUnit'
          description: Identifies the measurement unit being described.
          nullable: true
        name:
          type: string
          description: UI display name of the measurement unit. For example, 'Pound'.
          nullable: true
        abbreviation:
          type: string
          description: UI display abbreviation for the measurement unit. For example, 'lb'.
          nullable: true
    StandardUnitDescriptionGroup:
      type: object
      description: Group of standard measurement units.
      x-release-status: PUBLIC
      properties:
        standard_unit_descriptions:
          type: array
          items:
            $ref: '#/components/schemas/StandardUnitDescription'
          description: >-
            List of standard (non-custom) measurement units in this description
            group.
          nullable: true
        language_code:
          type: string
          description: IETF language tag.
          nullable: true
    SubmitEvidenceRequest:
      type: object
      description: Defines the parameters for a `SubmitEvidence` request.
      x-release-status: PUBLIC
      properties: {}
      example: {}
    SubmitEvidenceResponse:
      type: object
      description: Defines the fields in a `SubmitEvidence` response.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        dispute:
          $ref: '#/components/schemas/Dispute'
          description: The `Dispute` for which evidence was submitted.
      example:
        dispute:
          amount_money:
            amount: 4350
            currency: USD
          brand_dispute_id: '100000399240'
          card_brand: VISA
          created_at: '2022-05-18T16:02:15.313Z'
          disputed_payment:
            payment_id: 2yeBUWJzllJTpmnSqtMRAL19taB
          due_at: '2022-06-01T00:00:00.000Z'
          id: EAZoK70gX3fyvibecLwIGB
          location_id: LSY8XKGSMMX94
          reason: CUSTOMER_REQUESTS_CREDIT
          reported_at: '2022-05-18T00:00:00.000Z'
          state: PROCESSING
          updated_at: '2022-05-18T16:02:15.313Z'
          version: 4
    Subscription:
      type: object
      description: >-
        Represents a subscription purchased by a customer.


        For more information, see

        [Manage
        Subscriptions](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions).
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: The Square-assigned ID of the subscription.
          maxLength: 255
          readOnly: true
        location_id:
          type: string
          description: The ID of the location associated with the subscription.
          readOnly: true
        plan_variation_id:
          type: string
          description: >-
            The ID of the subscribed-to [subscription plan
            variation](entity:CatalogSubscriptionPlanVariation).
          readOnly: true
        customer_id:
          type: string
          description: The ID of the subscribing [customer](entity:Customer) profile.
          readOnly: true
        start_date:
          type: string
          description: >-
            The `YYYY-MM-DD`-formatted date (for example, 2013-01-15) to start
            the subscription.
          readOnly: true
        canceled_date:
          type: string
          description: >-
            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.
          nullable: true
        charged_through_date:
          type: string
          description: >-
            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.
          readOnly: true
        status:
          $ref: '#/components/schemas/SubscriptionStatus'
          description: >-
            The current status of the subscription.

            See [SubscriptionStatus](#type-subscriptionstatus) for possible
            values
          readOnly: true
        tax_percentage:
          type: string
          description: >-
            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%.
          nullable: true
        invoice_ids:
          type: array
          items:
            type: string
          description: |-
            The IDs of the [invoices](entity:Invoice) created for the
            subscription, listed in order when the invoices were created
            (newest invoices appear first).
          readOnly: true
        price_override_money:
          $ref: '#/components/schemas/Money'
          description: >-
            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).
          nullable: true
        version:
          type: integer
          description: >-
            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.
          format: int64
        created_at:
          type: string
          description: The timestamp when the subscription was created, in RFC 3339 format.
          readOnly: true
        card_id:
          type: string
          description: |-
            The ID of the [subscriber's](entity:Customer) [card](entity:Card)
            used to charge for the subscription.
          nullable: true
        timezone:
          type: string
          description: >-
            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`).
          readOnly: true
        source:
          $ref: '#/components/schemas/SubscriptionSource'
          description: The origination details of the subscription.
          x-release-status: BETA
          nullable: true
        actions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionAction'
          description: >-
            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"]`.
          x-release-status: BETA
          nullable: true
        monthly_billing_anchor_date:
          type: integer
          description: >-
            The day of the month on which the subscription will issue invoices
            and publish orders.
          readOnly: true
          x-release-status: BETA
        phases:
          type: array
          items:
            $ref: '#/components/schemas/Phase'
          description: array of phases for this subscription
          readOnly: true
    SubscriptionAction:
      type: object
      description: Represents an action as a pending change to a subscription.
      x-release-status: BETA
      properties:
        id:
          type: string
          description: The ID of an action scoped to a subscription.
        type:
          $ref: '#/components/schemas/SubscriptionActionType'
          description: >-
            The type of the action.

            See [SubscriptionActionType](#type-subscriptionactiontype) for
            possible values
          nullable: true
        effective_date:
          type: string
          description: >-
            The `YYYY-MM-DD`-formatted date when the action occurs on the
            subscription.
          nullable: true
        monthly_billing_anchor_date:
          type: integer
          description: >-
            The new billing anchor day value, for a `CHANGE_BILLING_ANCHOR_DATE`
            action.
          nullable: true
        phases:
          type: array
          items:
            $ref: '#/components/schemas/Phase'
          description: >-
            A list of Phases, to pass phase-specific information used in the
            swap.
          nullable: true
        new_plan_variation_id:
          type: string
          description: >-
            The target subscription plan variation that a subscription switches
            to, for a `SWAP_PLAN` action.
          nullable: true
    SubscriptionActionType:
      type: string
      enum:
        - CANCEL
        - PAUSE
        - RESUME
        - SWAP_PLAN
        - CHANGE_BILLING_ANCHOR_DATE
      x-enum-elements:
        - name: CANCEL
          description: The action to execute a scheduled cancellation of a subscription.
        - name: PAUSE
          description: The action to execute a scheduled pause of a subscription.
        - name: RESUME
          description: The action to execute a scheduled resumption of a subscription.
        - name: SWAP_PLAN
          description: >-
            The action to execute a scheduled swap of a subscription plan in a
            subscription.
        - name: CHANGE_BILLING_ANCHOR_DATE
          description: A billing anchor date change action.
      description: Supported types of an action as a pending change to a subscription.
      x-release-status: BETA
    SubscriptionCadence:
      type: string
      enum:
        - DAILY
        - WEEKLY
        - EVERY_TWO_WEEKS
        - THIRTY_DAYS
        - SIXTY_DAYS
        - NINETY_DAYS
        - MONTHLY
        - EVERY_TWO_MONTHS
        - QUARTERLY
        - EVERY_FOUR_MONTHS
        - EVERY_SIX_MONTHS
        - ANNUAL
        - EVERY_TWO_YEARS
      x-enum-elements:
        - name: DAILY
          description: Once per day
        - name: WEEKLY
          description: Once per week
        - name: EVERY_TWO_WEEKS
          description: Every two weeks
        - name: THIRTY_DAYS
          description: Once every 30 days
        - name: SIXTY_DAYS
          description: Once every 60 days
        - name: NINETY_DAYS
          description: Once every 90 days
        - name: MONTHLY
          description: Once per month
        - name: EVERY_TWO_MONTHS
          description: Once every two months
        - name: QUARTERLY
          description: Once every three months
        - name: EVERY_FOUR_MONTHS
          description: Once every four months
        - name: EVERY_SIX_MONTHS
          description: Once every six months
        - name: ANNUAL
          description: Once per year
        - name: EVERY_TWO_YEARS
          description: Once every two years
      description: Determines the billing cadence of a [Subscription](entity:Subscription)
      x-release-status: PUBLIC
    SubscriptionEvent:
      type: object
      description: Describes changes to a subscription and the subscription status.
      x-release-status: PUBLIC
      required:
        - id
        - subscription_event_type
        - effective_date
        - plan_variation_id
      properties:
        id:
          type: string
          description: The ID of the subscription event.
        subscription_event_type:
          $ref: '#/components/schemas/SubscriptionEventSubscriptionEventType'
          description: >-
            Type of the subscription event.

            See
            [SubscriptionEventSubscriptionEventType](#type-subscriptioneventsubscriptioneventtype)
            for possible values
        effective_date:
          type: string
          description: >-
            The `YYYY-MM-DD`-formatted date (for example, 2013-01-15) when the
            subscription event occurred.
        monthly_billing_anchor_date:
          type: integer
          description: >-
            The day-of-the-month the billing anchor date was changed to, if
            applicable.
          readOnly: true
          x-release-status: BETA
        info:
          $ref: '#/components/schemas/SubscriptionEventInfo'
          description: Additional information about the subscription event.
          nullable: true
        phases:
          type: array
          items:
            $ref: '#/components/schemas/Phase'
          description: >-
            A list of Phases, to pass phase-specific information used in the
            swap.
          nullable: true
        plan_variation_id:
          type: string
          description: >-
            The ID of the subscription plan variation associated with the
            subscription.
    SubscriptionEventInfo:
      type: object
      description: Provides information about the subscription event.
      x-release-status: PUBLIC
      properties:
        detail:
          type: string
          description: A human-readable explanation for the event.
          nullable: true
        code:
          $ref: '#/components/schemas/SubscriptionEventInfoCode'
          description: |-
            An info code indicating the subscription event that occurred.
            See [InfoCode](#type-infocode) for possible values
          nullable: true
    SubscriptionEventInfoCode:
      type: string
      enum:
        - LOCATION_NOT_ACTIVE
        - LOCATION_CANNOT_ACCEPT_PAYMENT
        - CUSTOMER_DELETED
        - CUSTOMER_NO_EMAIL
        - CUSTOMER_NO_NAME
        - USER_PROVIDED
      x-enum-elements:
        - name: LOCATION_NOT_ACTIVE
          description: The location is not active.
        - name: LOCATION_CANNOT_ACCEPT_PAYMENT
          description: The location cannot accept payments.
        - name: CUSTOMER_DELETED
          description: The subscribing customer profile has been deleted.
        - name: CUSTOMER_NO_EMAIL
          description: The subscribing customer does not have an email.
        - name: CUSTOMER_NO_NAME
          description: The subscribing customer does not have a name.
        - name: USER_PROVIDED
          description: User-provided detail.
      description: Supported info codes of a subscription event.
      x-release-status: PUBLIC
    SubscriptionEventSubscriptionEventType:
      type: string
      enum:
        - START_SUBSCRIPTION
        - PLAN_CHANGE
        - STOP_SUBSCRIPTION
        - DEACTIVATE_SUBSCRIPTION
        - RESUME_SUBSCRIPTION
        - PAUSE_SUBSCRIPTION
        - BILLING_ANCHOR_DATE_CHANGED
      x-enum-elements:
        - name: START_SUBSCRIPTION
          description: The subscription was started.
        - name: PLAN_CHANGE
          description: The subscription plan was changed.
        - name: STOP_SUBSCRIPTION
          description: The subscription was stopped.
        - name: DEACTIVATE_SUBSCRIPTION
          description: The subscription was deactivated
        - name: RESUME_SUBSCRIPTION
          description: The subscription was resumed.
        - name: PAUSE_SUBSCRIPTION
          description: The subscription was paused.
        - name: BILLING_ANCHOR_DATE_CHANGED
          description: The billing anchor date was changed.
      description: Supported types of an event occurred to a subscription.
      x-release-status: PUBLIC
    SubscriptionPhase:
      type: object
      description: >-
        Describes a phase in a subscription plan variation. For more
        information, see [Subscription Plans and
        Variations](https://developer.squareup.com/docs/subscriptions-api/plans-and-variations).
      x-release-status: PUBLIC
      required:
        - cadence
      properties:
        uid:
          type: string
          description: >-
            The Square-assigned ID of the subscription phase. This field cannot
            be changed after a `SubscriptionPhase` is created.
          nullable: true
        cadence:
          $ref: '#/components/schemas/SubscriptionCadence'
          description: >-
            The billing cadence of the phase. For example, weekly or monthly.
            This field cannot be changed after a `SubscriptionPhase` is created.

            See [SubscriptionCadence](#type-subscriptioncadence) for possible
            values
        periods:
          type: integer
          description: >-
            The number of `cadence`s the phase lasts. If not set, the phase
            never ends. Only the last phase can be indefinite. This field cannot
            be changed after a `SubscriptionPhase` is created.
          nullable: true
        recurring_price_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount to bill for each `cadence`. Failure to specify this field
            results in a `MISSING_REQUIRED_PARAMETER` error at runtime.
          nullable: true
        ordinal:
          type: integer
          description: >-
            The position this phase appears in the sequence of phases defined
            for the plan, indexed from 0. This field cannot be changed after a
            `SubscriptionPhase` is created.
          format: int64
          nullable: true
        pricing:
          $ref: '#/components/schemas/SubscriptionPricing'
          description: The subscription pricing.
          nullable: true
    SubscriptionPricing:
      type: object
      description: Describes the pricing for the subscription.
      x-release-status: PUBLIC
      properties:
        type:
          $ref: '#/components/schemas/SubscriptionPricingType'
          description: >-
            RELATIVE or STATIC

            See [SubscriptionPricingType](#type-subscriptionpricingtype) for
            possible values
          nullable: true
        discount_ids:
          type: array
          items:
            type: string
          description: The ids of the discount catalog objects
          nullable: true
        price_money:
          $ref: '#/components/schemas/Money'
          description: The price of the subscription, if STATIC
          nullable: true
    SubscriptionPricingType:
      type: string
      enum:
        - STATIC
        - RELATIVE
      x-enum-elements:
        - name: STATIC
          description: Static pricing
        - name: RELATIVE
          description: Relative pricing
      description: Determines the pricing of a [Subscription](entity:Subscription)
      x-release-status: PUBLIC
    SubscriptionSource:
      type: object
      description: The origination details of the subscription.
      x-release-status: BETA
      properties:
        name:
          type: string
          description: |-
            The name used to identify the place (physical or digital) that
            a subscription originates. If unset, the name defaults to the name
            of the application that created the subscription.
          maxLength: 255
          nullable: true
    SubscriptionStatus:
      type: string
      enum:
        - PENDING
        - ACTIVE
        - CANCELED
        - DEACTIVATED
        - PAUSED
      x-enum-elements:
        - name: PENDING
          description: The subscription is pending to start in the future.
        - name: ACTIVE
          description: The subscription is active.
        - name: CANCELED
          description: The subscription is canceled.
        - name: DEACTIVATED
          description: The subscription is deactivated.
        - name: PAUSED
          description: The subscription is paused.
      description: Supported subscription statuses.
      x-release-status: PUBLIC
    SubscriptionTestResult:
      type: object
      description: >-
        Represents the details of a webhook subscription, including notification
        URL,

        event types, and signature key.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: A Square-generated unique ID for the subscription test result.
          maxLength: 64
          readOnly: true
        status_code:
          type: integer
          description: The status code returned by the subscription notification URL.
          nullable: true
        payload:
          type: string
          description: >-
            An object containing the payload of the test event. For example, a
            `payment.created` event.
          nullable: true
        created_at:
          type: string
          description: >-
            The timestamp of when the subscription was created, in RFC 3339
            format. 

            For example, "2016-09-04T23:59:33.123Z".
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp of when the subscription was updated, in RFC 3339
            format. For example, "2016-09-04T23:59:33.123Z".

            Because a subscription test result is unique, this field is the same
            as the `created_at` field.
          readOnly: true
    SwapPlanRequest:
      type: object
      description: |-
        Defines input parameters in a call to the
        [SwapPlan](api-endpoint:Subscriptions-SwapPlan) endpoint.
      x-release-status: BETA
      properties:
        new_plan_variation_id:
          type: string
          description: |-
            The ID of the new subscription plan variation.

            This field is required.
          nullable: true
        phases:
          type: array
          items:
            $ref: '#/components/schemas/PhaseInput'
          description: >-
            A list of PhaseInputs, to pass phase-specific information used in
            the swap.
          nullable: true
      example:
        new_plan_variation_id: FQ7CDXXWSLUJRPM3GFJSJGZ7
        phases:
          - order_template_id: uhhnjH9osVv3shUADwaC0b3hNxQZY
            ordinal: 0
    SwapPlanResponse:
      type: object
      description: |-
        Defines output parameters in a response of the 
        [SwapPlan](api-endpoint:Subscriptions-SwapPlan) endpoint.
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered during the request.
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: The subscription with the updated subscription plan.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionAction'
          description: A list of a `SWAP_PLAN` action created by the request.
      example:
        actions:
          - effective_date: '2023-11-17'
            id: f0a1dfdc-675b-3a14-a640-99f7ac1cee83
            new_plan_variation_id: FQ7CDXXWSLUJRPM3GFJSJGZ7
            phases:
              - order_template_id: uhhnjH9osVv3shUADwaC0b3hNxQZY
                ordinal: 0
            type: SWAP_PLAN
        subscription:
          created_at: '2023-06-20T21:53:10Z'
          customer_id: CHFGVKYY8RSV93M5KCYTG4PN0G
          id: 9ba40961-995a-4a3d-8c53-048c40cafc13
          location_id: S8GWD5R9QB376
          phases:
            - order_template_id: E6oBY5WfQ2eN4pkYZwq4ka6n7KeZY
              ordinal: 0
              plan_phase_uid: C66BKH3ASTDYGJJCEZXQQSS7
              uid: 98d6f53b-40e1-4714-8827-032fd923be25
          plan_variation_id: FQ7CDXXWSLUJRPM3GFJSJGZ7
          price_override_money:
            amount: 2000
            currency: USD
          source:
            name: My Application
          status: ACTIVE
          timezone: America/Los_Angeles
          version: 3
    TaxCalculationPhase:
      type: string
      enum:
        - TAX_SUBTOTAL_PHASE
        - TAX_TOTAL_PHASE
      x-enum-elements:
        - name: TAX_SUBTOTAL_PHASE
          description: The fee is calculated based on the payment's subtotal.
        - name: TAX_TOTAL_PHASE
          description: The fee is calculated based on the payment's total.
      description: When to calculate the taxes due on a cart.
      x-release-status: PUBLIC
    TaxIds:
      type: object
      description: >-
        Identifiers for the location used by various governments for tax
        purposes.
      x-release-status: BETA
      properties:
        eu_vat:
          type: string
          description: |-
            The EU VAT number for this location. For example, `IE3426675K`.
            If the EU VAT number is present, it is well-formed and has been
            validated with VIES, the VAT Information Exchange System.
          readOnly: true
        fr_siret:
          type: string
          description: >-
            The SIRET (Syst�me d'Identification du R�pertoire des Entreprises et
            de leurs Etablissements)

            number is a 14-digit code issued by the French INSEE. For example,
            `39922799000021`.
          readOnly: true
        fr_naf:
          type: string
          description: >-
            The French government uses the NAF (Nomenclature des Activit�s
            Fran�aises) to display and

            track economic statistical data. This is also called the APE
            (Activite Principale de lEntreprise) code.

            For example, `6910Z`.
          readOnly: true
        es_nif:
          type: string
          description: >-
            The NIF (Numero de Identificacion Fiscal) number is a nine-character
            tax identifier used in Spain.

            If it is present, it has been validated. For example, `73628495A`.
          readOnly: true
        jp_qii:
          type: string
          description: >-
            The QII (Qualified Invoice Issuer) number is a 14-character tax
            identifier used in Japan.

            For example, `T1234567890123`.
          readOnly: true
    TaxInclusionType:
      type: string
      enum:
        - ADDITIVE
        - INCLUSIVE
      x-enum-elements:
        - name: ADDITIVE
          description: >-
            The tax is an additive tax. The tax amount is added on top of the

            CatalogItemVariation price. For example, a $1.00 item with a 10%
            additive

            tax would have a total cost to the buyer of $1.10.
        - name: INCLUSIVE
          description: >-
            The tax is an inclusive tax. The tax amount is included in the

            CatalogItemVariation price. For example, a $1.00 item with a 10%
            inclusive

            tax would have a total cost to the buyer of $1.00, with $0.91 (91
            cents) of

            that total being the cost of the item and $0.09 (9 cents) being tax.
      description: >-
        Whether to the tax amount should be additional to or included in the
        CatalogItem price.
      x-release-status: PUBLIC
    TeamMember:
      type: object
      description: A record representing an individual team member for a business.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: The unique ID for the team member.
          readOnly: true
        reference_id:
          type: string
          description: >-
            A second ID used to associate the team member with an entity in
            another system.
          nullable: true
        is_owner:
          type: boolean
          description: Whether the team member is the owner of the Square account.
          readOnly: true
        status:
          $ref: '#/components/schemas/TeamMemberStatus'
          description: |-
            Describes the status of the team member.
            See [TeamMemberStatus](#type-teammemberstatus) for possible values
          nullable: true
        given_name:
          type: string
          description: >-
            The given name (that is, the first name) associated with the team
            member.
          nullable: true
        family_name:
          type: string
          description: >-
            The family name (that is, the last name) associated with the team
            member.
          nullable: true
        email_address:
          type: string
          description: >-
            The email address associated with the team member. After accepting
            the invitation

            from Square, only the team member can change this value.
          nullable: true
        phone_number:
          type: string
          description: |-
            The team member's phone number, in E.164 format. For example:
            +14155552671 - the country code is 1 for US
            +551155256325 - the country code is 55 for BR
          nullable: true
        created_at:
          type: string
          description: The timestamp when the team member was created, in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp when the team member was last updated, in RFC 3339
            format.
          readOnly: true
        assigned_locations:
          $ref: '#/components/schemas/TeamMemberAssignedLocations'
          description: Describes the team member's assigned locations.
          nullable: true
        wage_setting:
          $ref: '#/components/schemas/WageSetting'
          description: >-
            Information about the team member's overtime exemption status, job
            assignments, and compensation.
          x-release-status: BETA
          nullable: true
    TeamMemberAssignedLocations:
      type: object
      description: An object that represents a team member's assignment to locations.
      x-release-status: PUBLIC
      properties:
        assignment_type:
          $ref: '#/components/schemas/TeamMemberAssignedLocationsAssignmentType'
          description: >-
            The current assignment type of the team member.

            See
            [TeamMemberAssignedLocationsAssignmentType](#type-teammemberassignedlocationsassignmenttype)
            for possible values
          nullable: true
        location_ids:
          type: array
          items:
            type: string
          description: The explicit locations that the team member is assigned to.
          nullable: true
    TeamMemberAssignedLocationsAssignmentType:
      type: string
      enum:
        - ALL_CURRENT_AND_FUTURE_LOCATIONS
        - EXPLICIT_LOCATIONS
      x-enum-elements:
        - name: ALL_CURRENT_AND_FUTURE_LOCATIONS
          description: >-
            The team member is assigned to all current and future locations. The
            `location_ids` field

            is empty if the team member has this assignment type.
        - name: EXPLICIT_LOCATIONS
          description: >-
            The team member is assigned to an explicit subset of locations. The
            `location_ids` field

            is the list of locations that the team member is assigned to.
      description: Enumerates the possible assignment types that the team member can have.
      x-release-status: PUBLIC
    TeamMemberBookingProfile:
      type: object
      description: >-
        The booking profile of a seller's team member, including the team
        member's ID, display name, description and whether the team member can
        be booked as a service provider.
      x-release-status: PUBLIC
      properties:
        team_member_id:
          type: string
          description: >-
            The ID of the [TeamMember](entity:TeamMember) object for the team
            member associated with the booking profile.
          maxLength: 32
          readOnly: true
        description:
          type: string
          description: The description of the team member.
          maxLength: 65536
          readOnly: true
        display_name:
          type: string
          description: The display name of the team member.
          maxLength: 512
          readOnly: true
        is_bookable:
          type: boolean
          description: >-
            Indicates whether the team member can be booked through the Bookings
            API or the seller's online booking channel or site (`true`) or not
            (`false`).
          nullable: true
        profile_image_url:
          type: string
          description: The URL of the team member's image for the bookings profile.
          maxLength: 2048
          readOnly: true
    TeamMemberInvitationStatus:
      type: string
      enum:
        - UNINVITED
        - PENDING
        - ACCEPTED
      x-enum-elements:
        - name: UNINVITED
          description: The team member has not received an invitation.
        - name: PENDING
          description: The team member has received an invitation, but had not accepted it.
        - name: ACCEPTED
          description: The team member has both received and accepted an invitation.
      description: >-
        Enumerates the possible invitation statuses the team member can have
        within a business.
      x-release-status: PUBLIC
    TeamMemberStatus:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
      x-enum-elements:
        - name: ACTIVE
          description: >-
            The team member can sign in to Point of Sale and the Seller
            Dashboard.
        - name: INACTIVE
          description: >-
            The team member can no longer sign in to Point of Sale or the Seller
            Dashboard,

            but the team member's sales reports remain available.
      description: >-
        Enumerates the possible statuses the team member can have within a
        business.
      x-release-status: PUBLIC
    TeamMemberWage:
      type: object
      description: >-
        The hourly wage rate that a team member earns on a `Shift` for doing the
        job

        specified by the `title` property of this object.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: The UUID for this object.
        team_member_id:
          type: string
          description: The `TeamMember` that this wage is assigned to.
          nullable: true
        title:
          type: string
          description: The job title that this wage relates to.
          nullable: true
        hourly_rate:
          $ref: '#/components/schemas/Money'
          description: |-
            Can be a custom-set hourly wage or the calculated effective hourly
            wage based on the annual wage and hours worked per week.
          nullable: true
        job_id:
          type: string
          description: |-
            An identifier for the job that this wage relates to. This cannot be
            used to retrieve the job.
          nullable: true
        tip_eligible:
          type: boolean
          description: Whether team members are eligible for tips when working this job.
          nullable: true
    Tender:
      type: object
      description: >-
        Represents a tender (i.e., a method of payment) used in a Square
        transaction.
      x-release-status: PUBLIC
      required:
        - type
      properties:
        id:
          type: string
          description: The tender's unique ID. It is the associated payment ID.
          maxLength: 192
        location_id:
          type: string
          description: The ID of the transaction's associated location.
          maxLength: 50
          nullable: true
        transaction_id:
          type: string
          description: The ID of the tender's associated transaction.
          maxLength: 192
          nullable: true
        created_at:
          type: string
          description: The timestamp for when the tender was created, in RFC 3339 format.
          maxLength: 32
          readOnly: true
        note:
          type: string
          description: An optional note associated with the tender at the time of payment.
          maxLength: 500
          nullable: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The total amount of the tender, including `tip_money`. If the tender
            has a `payment_id`,

            the `total_money` of the corresponding [Payment](entity:Payment)
            will be equal to the

            `amount_money` of the tender.
          nullable: true
        tip_money:
          $ref: '#/components/schemas/Money'
          description: The tip's amount of the tender.
          nullable: true
        processing_fee_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of any Square processing fees applied to the tender.


            This field is not immediately populated when a new transaction is
            created.

            It is usually available after about ten seconds.
          nullable: true
        customer_id:
          type: string
          description: >-
            If the tender is associated with a customer or represents a
            customer's card on file,

            this is the ID of the associated customer.
          maxLength: 191
          nullable: true
        type:
          $ref: '#/components/schemas/TenderType'
          description: |-
            The type of tender, such as `CARD` or `CASH`.
            See [TenderType](#type-tendertype) for possible values
        card_details:
          $ref: '#/components/schemas/TenderCardDetails'
          description: |-
            The details of the card tender.

            This value is present only if the value of `type` is `CARD`.
          nullable: true
        cash_details:
          $ref: '#/components/schemas/TenderCashDetails'
          description: |-
            The details of the cash tender.

            This value is present only if the value of `type` is `CASH`.
          nullable: true
        bank_account_details:
          $ref: '#/components/schemas/TenderBankAccountDetails'
          description: |-
            The details of the bank account tender.

            This value is present only if the value of `type` is `BANK_ACCOUNT`.
          nullable: true
        buy_now_pay_later_details:
          $ref: '#/components/schemas/TenderBuyNowPayLaterDetails'
          description: >-
            The details of a Buy Now Pay Later tender.


            This value is present only if the value of `type` is
            `BUY_NOW_PAY_LATER`.
          nullable: true
        square_account_details:
          $ref: '#/components/schemas/TenderSquareAccountDetails'
          description: >-
            The details of a Square Account tender.


            This value is present only if the value of `type` is
            `SQUARE_ACCOUNT`.
          nullable: true
        additional_recipients:
          type: array
          items:
            $ref: '#/components/schemas/AdditionalRecipient'
          description: >-
            Additional recipients (other than the merchant) receiving a portion
            of this tender.

            For example, fees assessed on the purchase by a third party
            integration.
          x-release-status: DEPRECATED
          nullable: true
        payment_id:
          type: string
          description: >-
            The ID of the [Payment](entity:Payment) that corresponds to this
            tender.

            This value is only present for payments created with the v2 Payments
            API.
          maxLength: 192
          nullable: true
    TenderBankAccountDetails:
      type: object
      description: |-
        Represents the details of a tender with `type` `BANK_ACCOUNT`.

        See [BankAccountPaymentDetails](entity:BankAccountPaymentDetails)
        for more exposed details of a bank account payment.
      x-release-status: PUBLIC
      properties:
        status:
          $ref: '#/components/schemas/TenderBankAccountDetailsStatus'
          description: >-
            The bank account payment's current state.


            See
            [TenderBankAccountPaymentDetailsStatus](entity:TenderBankAccountDetailsStatus)
            for possible values.

            See
            [TenderBankAccountDetailsStatus](#type-tenderbankaccountdetailsstatus)
            for possible values
          nullable: true
    TenderBankAccountDetailsStatus:
      type: string
      enum:
        - PENDING
        - COMPLETED
        - FAILED
      x-enum-elements:
        - name: PENDING
          description: The bank account payment is in progress.
        - name: COMPLETED
          description: The bank account payment has been completed.
        - name: FAILED
          description: The bank account payment failed.
      description: Indicates the bank account payment's current status.
      x-release-status: PUBLIC
    TenderBuyNowPayLaterDetails:
      type: object
      description: Represents the details of a tender with `type` `BUY_NOW_PAY_LATER`.
      x-release-status: PUBLIC
      properties:
        buy_now_pay_later_brand:
          $ref: '#/components/schemas/TenderBuyNowPayLaterDetailsBrand'
          description: |-
            The Buy Now Pay Later brand.
            See [Brand](#type-brand) for possible values
          readOnly: true
        status:
          $ref: '#/components/schemas/TenderBuyNowPayLaterDetailsStatus'
          description: >-
            The buy now pay later payment's current state (such as `AUTHORIZED`
            or

            `CAPTURED`). See
            [TenderBuyNowPayLaterDetailsStatus](entity:TenderBuyNowPayLaterDetailsStatus)

            for possible values.

            See [Status](#type-status) for possible values
          nullable: true
    TenderBuyNowPayLaterDetailsBrand:
      type: string
      enum:
        - OTHER_BRAND
        - AFTERPAY
      x-enum-elements:
        - name: OTHER_BRAND
          description: ''
        - name: AFTERPAY
          description: ''
      x-release-status: PUBLIC
    TenderBuyNowPayLaterDetailsStatus:
      type: string
      enum:
        - AUTHORIZED
        - CAPTURED
        - VOIDED
        - FAILED
      x-enum-elements:
        - name: AUTHORIZED
          description: >-
            The buy now pay later payment has been authorized but not yet
            captured.
        - name: CAPTURED
          description: >-
            The buy now pay later payment was authorized and subsequently
            captured (i.e., completed).
        - name: VOIDED
          description: >-
            The buy now pay later payment was authorized and subsequently voided
            (i.e., canceled).
        - name: FAILED
          description: The buy now pay later payment failed.
      x-release-status: PUBLIC
    TenderCardDetails:
      type: object
      description: >-
        Represents additional details of a tender with `type` `CARD` or
        `SQUARE_GIFT_CARD`
      x-release-status: PUBLIC
      properties:
        status:
          $ref: '#/components/schemas/TenderCardDetailsStatus'
          description: >-
            The credit card payment's current state (such as `AUTHORIZED` or

            `CAPTURED`). See
            [TenderCardDetailsStatus](entity:TenderCardDetailsStatus)

            for possible values.

            See [TenderCardDetailsStatus](#type-tendercarddetailsstatus) for
            possible values
          nullable: true
        card:
          $ref: '#/components/schemas/Card'
          description: The credit card's non-confidential details.
          nullable: true
        entry_method:
          $ref: '#/components/schemas/TenderCardDetailsEntryMethod'
          description: >-
            The method used to enter the card's details for the transaction.

            See
            [TenderCardDetailsEntryMethod](#type-tendercarddetailsentrymethod)
            for possible values
          nullable: true
    TenderCardDetailsEntryMethod:
      type: string
      enum:
        - SWIPED
        - KEYED
        - EMV
        - ON_FILE
        - CONTACTLESS
      x-enum-elements:
        - name: SWIPED
          description: The card was swiped through a Square reader or Square stand.
        - name: KEYED
          description: >-
            The card information was keyed manually into Square Point of Sale or
            a

            Square-hosted web form.
        - name: EMV
          description: The card was processed via EMV with a Square reader.
        - name: ON_FILE
          description: The buyer's card details were already on file with Square.
        - name: CONTACTLESS
          description: |-
            The card was processed via a contactless (i.e., NFC) transaction
            with a Square reader.
      description: Indicates the method used to enter the card's details.
      x-release-status: PUBLIC
    TenderCardDetailsStatus:
      type: string
      enum:
        - AUTHORIZED
        - CAPTURED
        - VOIDED
        - FAILED
      x-enum-elements:
        - name: AUTHORIZED
          description: The card transaction has been authorized but not yet captured.
        - name: CAPTURED
          description: >-
            The card transaction was authorized and subsequently captured (i.e.,
            completed).
        - name: VOIDED
          description: >-
            The card transaction was authorized and subsequently voided (i.e.,
            canceled).
        - name: FAILED
          description: The card transaction failed.
      description: Indicates the card transaction's current status.
      x-release-status: PUBLIC
    TenderCashDetails:
      type: object
      description: Represents the details of a tender with `type` `CASH`.
      x-release-status: PUBLIC
      properties:
        buyer_tendered_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The total amount of cash provided by the buyer, before change is
            given.
          nullable: true
        change_back_money:
          $ref: '#/components/schemas/Money'
          description: The amount of change returned to the buyer.
          nullable: true
    TenderSquareAccountDetails:
      type: object
      description: Represents the details of a tender with `type` `SQUARE_ACCOUNT`.
      x-release-status: PUBLIC
      properties:
        status:
          $ref: '#/components/schemas/TenderSquareAccountDetailsStatus'
          description: >-
            The Square Account payment's current state (such as `AUTHORIZED` or

            `CAPTURED`). See
            [TenderSquareAccountDetailsStatus](entity:TenderSquareAccountDetailsStatus)

            for possible values.

            See [Status](#type-status) for possible values
          nullable: true
    TenderSquareAccountDetailsStatus:
      type: string
      enum:
        - AUTHORIZED
        - CAPTURED
        - VOIDED
        - FAILED
      x-enum-elements:
        - name: AUTHORIZED
          description: The Square Account payment has been authorized but not yet captured.
        - name: CAPTURED
          description: >-
            The Square Account payment was authorized and subsequently captured
            (i.e., completed).
        - name: VOIDED
          description: >-
            The Square Account payment was authorized and subsequently voided
            (i.e., canceled).
        - name: FAILED
          description: The Square Account payment failed.
      x-release-status: PUBLIC
    TenderType:
      type: string
      enum:
        - CARD
        - CASH
        - THIRD_PARTY_CARD
        - SQUARE_GIFT_CARD
        - NO_SALE
        - BANK_ACCOUNT
        - WALLET
        - BUY_NOW_PAY_LATER
        - SQUARE_ACCOUNT
        - OTHER
      x-enum-elements:
        - name: CARD
          description: A credit card.
        - name: CASH
          description: Cash.
        - name: THIRD_PARTY_CARD
          description: >-
            A credit card processed with a card processor other than Square.


            This value applies only to merchants in countries where Square does
            not

            yet provide card processing.
        - name: SQUARE_GIFT_CARD
          description: A Square gift card.
        - name: NO_SALE
          description: >-
            This tender represents the register being opened for a "no sale"
            event.
        - name: BANK_ACCOUNT
          description: A bank account payment.
        - name: WALLET
          description: >-
            A payment from a digital wallet, e.g. Cash App, Paypay, Rakuten Pay,

            Au Pay, D Barai, Merpay, Wechat Pay, Alipay.


            Note: Some "digital wallets", including Google Pay and Apple Pay,
            facilitate

            card payments.  Those payments have the `CARD` type.
        - name: BUY_NOW_PAY_LATER
          description: A Buy Now Pay Later payment.
        - name: SQUARE_ACCOUNT
          description: A Square House Account payment.
        - name: OTHER
          description: A form of tender that does not match any other value.
      description: Indicates a tender's type.
      x-release-status: PUBLIC
    TerminalAction:
      type: object
      description: Represents an action processed by the Square Terminal.
      x-release-status: BETA
      properties:
        id:
          type: string
          description: A unique ID for this `TerminalAction`.
          minLength: 10
          maxLength: 255
          readOnly: true
        device_id:
          type: string
          description: |-
            The unique Id of the device intended for this `TerminalAction`.
            The Id can be retrieved from /v2/devices api.
          nullable: true
        deadline_duration:
          type: string
          description: >-
            The duration as an RFC 3339 duration, after which the action will be
            automatically canceled.

            TerminalActions that are `PENDING` will be automatically `CANCELED`
            and have a cancellation reason

            of `TIMED_OUT`


            Default: 5 minutes from creation


            Maximum: 5 minutes
          nullable: true
        status:
          type: string
          description: >-
            The status of the `TerminalAction`.

            Options: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`,
            `COMPLETED`
          readOnly: true
        cancel_reason:
          $ref: '#/components/schemas/ActionCancelReason'
          description: >-
            The reason why `TerminalAction` is canceled. Present if the status
            is `CANCELED`.

            See [ActionCancelReason](#type-actioncancelreason) for possible
            values
          readOnly: true
        created_at:
          type: string
          description: >-
            The time when the `TerminalAction` was created as an RFC 3339
            timestamp.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The time when the `TerminalAction` was last updated as an RFC 3339
            timestamp.
          readOnly: true
        app_id:
          type: string
          description: The ID of the application that created the action.
          readOnly: true
        location_id:
          type: string
          description: The location id the action is attached to, if a link can be made.
          maxLength: 64
          readOnly: true
          x-release-status: PUBLIC
        type:
          $ref: '#/components/schemas/TerminalActionActionType'
          description: |-
            Represents the type of the action.
            See [ActionType](#type-actiontype) for possible values
          nullable: true
        qr_code_options:
          $ref: '#/components/schemas/QrCodeOptions'
          description: >-
            Describes configuration for the QR code action. Requires `QR_CODE`
            type.
          nullable: true
        save_card_options:
          $ref: '#/components/schemas/SaveCardOptions'
          description: >-
            Describes configuration for the save-card action. Requires
            `SAVE_CARD` type.
          nullable: true
        signature_options:
          $ref: '#/components/schemas/SignatureOptions'
          description: >-
            Describes configuration for the signature capture action. Requires
            `SIGNATURE` type.
          nullable: true
        confirmation_options:
          $ref: '#/components/schemas/ConfirmationOptions'
          description: >-
            Describes configuration for the confirmation action. Requires
            `CONFIRMATION` type.
          nullable: true
        receipt_options:
          $ref: '#/components/schemas/ReceiptOptions'
          description: >-
            Describes configuration for the receipt action. Requires `RECEIPT`
            type.
          nullable: true
        data_collection_options:
          $ref: '#/components/schemas/DataCollectionOptions'
          description: >-
            Describes configuration for the data collection action. Requires
            `DATA_COLLECTION` type.
          nullable: true
        select_options:
          $ref: '#/components/schemas/SelectOptions'
          description: >-
            Describes configuration for the select action. Requires `SELECT`
            type.
          nullable: true
        device_metadata:
          $ref: '#/components/schemas/DeviceMetadata'
          description: >-
            Details about the Terminal that received the action request (such as
            battery level,

            operating system version, and network connection settings).


            Only available for `PING` action type.
          readOnly: true
        await_next_action:
          type: boolean
          description: >-
            Indicates the action will be linked to another action and requires a
            waiting dialog to be

            displayed instead of returning to the idle screen on completion of
            the action.


            Only supported on SIGNATURE, CONFIRMATION, DATA_COLLECTION, and
            SELECT types.
          nullable: true
        await_next_action_duration:
          type: string
          description: >-
            The timeout duration of the waiting dialog as an RFC 3339 duration,
            after which the

            waiting dialog will no longer be displayed and the Terminal will
            return to the idle screen.


            Default: 5 minutes from when the waiting dialog is displayed


            Maximum: 5 minutes
          nullable: true
    TerminalActionActionType:
      type: string
      enum:
        - QR_CODE
        - PING
        - SAVE_CARD
        - SIGNATURE
        - CONFIRMATION
        - RECEIPT
        - DATA_COLLECTION
        - SELECT
      x-enum-elements:
        - name: QR_CODE
          description: >-
            The action represents a request to display a QR code. Details are
            contained in

            the `qr_code_options` object.
        - name: PING
          description: >-
            The action represents a request to check if the specific device is

            online or currently active with the merchant in question. Does not
            require an action options value.
        - name: SAVE_CARD
          description: >-
            Represents a request to save a card for future card-on-file use.
            Details are contained

            in the `save_card_options` object.
        - name: SIGNATURE
          description: >-
            The action represents a request to capture a buyer's signature.
            Details are contained

            in the `signature_options` object.
        - name: CONFIRMATION
          description: >-
            The action represents a request to collect a buyer's confirmation
            decision to the

            displayed terms. Details are contained in the `confirmation_options`
            object.
        - name: RECEIPT
          description: >-
            The action represents a request to display the receipt screen
            options. Details are

            contained in the `receipt_options` object.
        - name: DATA_COLLECTION
          description: >-
            The action represents a request to collect a buyer's text data.
            Details

            are contained in the `data_collection_options` object.
        - name: SELECT
          description: >-
            The action represents a request to allow the buyer to select from
            provided options.

            Details are contained in the `select_options` object.
      description: >-
        Describes the type of this unit and indicates which field contains the
        unit information. This is an open enum.
      x-release-status: BETA
    TerminalActionQuery:
      type: object
      x-release-status: BETA
      properties:
        filter:
          $ref: '#/components/schemas/TerminalActionQueryFilter'
          description: Options for filtering returned `TerminalAction`s
          nullable: true
        sort:
          $ref: '#/components/schemas/TerminalActionQuerySort'
          description: Option for sorting returned `TerminalAction` objects.
          nullable: true
      example:
        include:
          - CUSTOMER
        limit: 2
        query:
          filter:
            status: COMPLETED
    TerminalActionQueryFilter:
      type: object
      x-release-status: BETA
      properties:
        device_id:
          type: string
          description: >-
            `TerminalAction`s associated with a specific device. If no device is
            specified then all

            `TerminalAction`s for the merchant will be displayed.
          nullable: true
        created_at:
          $ref: '#/components/schemas/TimeRange'
          description: >-
            Time range for the beginning of the reporting period. Inclusive.

            Default value: The current time minus one day.

            Note that `TerminalAction`s are available for 30 days after
            creation.
        status:
          type: string
          description: >-
            Filter results with the desired status of the `TerminalAction`

            Options: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`,
            `COMPLETED`
          nullable: true
        type:
          $ref: '#/components/schemas/TerminalActionActionType'
          description: >-
            Filter results with the requested ActionType.

            See [TerminalActionActionType](#type-terminalactionactiontype) for
            possible values
          nullable: true
    TerminalActionQuerySort:
      type: object
      x-release-status: BETA
      properties:
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            The order in which results are listed.
            - `ASC` - Oldest to newest.
            - `DESC` - Newest to oldest (default).
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
    TerminalCheckout:
      type: object
      description: Represents a checkout processed by the Square Terminal.
      x-release-status: PUBLIC
      required:
        - amount_money
        - device_options
      properties:
        id:
          type: string
          description: A unique ID for this `TerminalCheckout`.
          minLength: 10
          maxLength: 255
          readOnly: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money (including the tax amount) that the Square
            Terminal device should try to collect.
        reference_id:
          type: string
          description: >-
            An optional user-defined reference ID that can be used to associate

            this `TerminalCheckout` to another entity in an external system. For
            example, an order

            ID generated by a third-party shopping cart. The ID is also
            associated with any payments

            used to complete the checkout.
          maxLength: 40
          nullable: true
        note:
          type: string
          description: >-
            An optional note to associate with the checkout, as well as with any
            payments used to complete the checkout.

            Note: maximum 500 characters
          maxLength: 500
          nullable: true
        order_id:
          type: string
          description: >-
            The reference to the Square order ID for the checkout request.
            Supported only in the US.
          nullable: true
        payment_options:
          $ref: '#/components/schemas/PaymentOptions'
          description: >-
            Payment-specific options for the checkout request. Supported only in
            the US.
          nullable: true
        device_options:
          $ref: '#/components/schemas/DeviceCheckoutOptions'
          description: >-
            Options to control the display and behavior of the Square Terminal
            device.
        deadline_duration:
          type: string
          description: >-
            An RFC 3339 duration, after which the checkout is automatically
            canceled.

            A `TerminalCheckout` that is `PENDING` is automatically `CANCELED`
            and has a cancellation reason

            of `TIMED_OUT`.


            Default: 5 minutes from creation


            Maximum: 5 minutes
          x-release-status: DEPRECATED
          nullable: true
        status:
          type: string
          description: >-
            The status of the `TerminalCheckout`.

            Options: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`,
            `COMPLETED`
          readOnly: true
        cancel_reason:
          $ref: '#/components/schemas/ActionCancelReason'
          description: >-
            The reason why `TerminalCheckout` is canceled. Present if the status
            is `CANCELED`.

            See [ActionCancelReason](#type-actioncancelreason) for possible
            values
          readOnly: true
        payment_ids:
          type: array
          items:
            type: string
          description: A list of IDs for payments created by this `TerminalCheckout`.
          readOnly: true
        created_at:
          type: string
          description: >-
            The time when the `TerminalCheckout` was created, as an RFC 3339
            timestamp.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The time when the `TerminalCheckout` was last updated, as an RFC
            3339 timestamp.
          readOnly: true
        app_id:
          type: string
          description: The ID of the application that created the checkout.
          readOnly: true
        location_id:
          type: string
          description: >-
            The location of the device where the `TerminalCheckout` was
            directed.
          maxLength: 64
          readOnly: true
        payment_type:
          $ref: '#/components/schemas/CheckoutOptionsPaymentType'
          description: >-
            The type of payment the terminal should attempt to capture from.
            Defaults to `CARD_PRESENT`.

            See [CheckoutOptionsPaymentType](#type-checkoutoptionspaymenttype)
            for possible values
          nullable: true
        team_member_id:
          type: string
          description: >-
            An optional ID of the team member associated with creating the
            checkout.
          x-release-status: BETA
          nullable: true
        customer_id:
          type: string
          description: An optional ID of the customer associated with the checkout.
          nullable: true
        app_fee_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount the developer is taking as a fee for facilitating the
            payment on behalf

            of the seller.


            The amount cannot be more than 90% of the total amount of the
            payment.


            The amount must be specified in the smallest denomination of the
            applicable currency (for example, US dollar amounts are specified in
            cents). For more information, see [Working with Monetary
            Amounts](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts).


            The fee currency code must match the currency associated with the
            seller that is accepting the payment. The application must be from a
            developer account in the same country and using the same currency
            code as the seller.


            For more information about the application fee scenario, see [Take
            Payments and Collect
            Fees](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees).


            To set this field, PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth
            permission is required. For more information, see
            [Permissions](https://developer.squareup.com/docs/payments-api/take-payments-and-collect-fees#permissions).


            Supported only in the US.
          nullable: true
        statement_description_identifier:
          type: string
          description: >-
            Optional additional payment information to include on the customer's
            card statement as

            part of the statement description. This can be, for example, an
            invoice number, ticket number,

            or short description that uniquely identifies the purchase.
            Supported only in the US.
          maxLength: 20
          x-release-status: BETA
          nullable: true
        tip_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount designated as a tip, in addition to `amount_money`. This
            may only be set for a

            checkout that has tipping disabled (`tip_settings.allow_tipping` is
            `false`). Supported only in

            the US.
          x-release-status: BETA
          nullable: true
    TerminalCheckoutQuery:
      type: object
      x-release-status: PUBLIC
      properties:
        filter:
          $ref: '#/components/schemas/TerminalCheckoutQueryFilter'
          description: Options for filtering returned `TerminalCheckout` objects.
          nullable: true
        sort:
          $ref: '#/components/schemas/TerminalCheckoutQuerySort'
          description: Option for sorting returned `TerminalCheckout` objects.
          nullable: true
    TerminalCheckoutQueryFilter:
      type: object
      x-release-status: PUBLIC
      properties:
        device_id:
          type: string
          description: >-
            The `TerminalCheckout` objects associated with a specific device. If
            no device is specified, then all

            `TerminalCheckout` objects for the merchant are displayed.
          nullable: true
        created_at:
          $ref: '#/components/schemas/TimeRange'
          description: >-
            The time range for the beginning of the reporting period, which is
            inclusive.

            Default value: The current time minus one day.

            Note that `TerminalCheckout`s are available for 30 days after
            creation.
        status:
          type: string
          description: >-
            Filtered results with the desired status of the `TerminalCheckout`.

            Options: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`,
            `COMPLETED`
          nullable: true
    TerminalCheckoutQuerySort:
      type: object
      x-release-status: PUBLIC
      properties:
        sort_order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            The order in which results are listed.
            Default: `DESC`
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
    TerminalRefund:
      type: object
      description: >-
        Represents a payment refund processed by the Square Terminal. Only
        supports Interac (Canadian debit network) payment refunds.
      x-release-status: PUBLIC
      required:
        - payment_id
        - amount_money
        - reason
        - device_id
      properties:
        id:
          type: string
          description: A unique ID for this `TerminalRefund`.
          minLength: 10
          maxLength: 255
          readOnly: true
        refund_id:
          type: string
          description: >-
            The reference to the payment refund created by completing this
            `TerminalRefund`.
          readOnly: true
        payment_id:
          type: string
          description: The unique ID of the payment being refunded.
          minLength: 1
        order_id:
          type: string
          description: >-
            The reference to the Square order ID for the payment identified by
            the `payment_id`.
          readOnly: true
        amount_money:
          $ref: '#/components/schemas/Money'
          description: >-
            The amount of money, inclusive of `tax_money`, that the
            `TerminalRefund` should return.

            This value is limited to the amount taken in the original payment
            minus any completed or

            pending refunds.
        reason:
          type: string
          description: A description of the reason for the refund.
          maxLength: 192
        device_id:
          type: string
          description: |-
            The unique ID of the device intended for this `TerminalRefund`.
            The Id can be retrieved from /v2/devices api.
        deadline_duration:
          type: string
          description: >-
            The RFC 3339 duration, after which the refund is automatically
            canceled.

            A `TerminalRefund` that is `PENDING` is automatically `CANCELED` and
            has a cancellation reason

            of `TIMED_OUT`.


            Default: 5 minutes from creation.


            Maximum: 5 minutes
          nullable: true
        status:
          type: string
          description: >-
            The status of the `TerminalRefund`.

            Options: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`,
            or `COMPLETED`.
          readOnly: true
        cancel_reason:
          $ref: '#/components/schemas/ActionCancelReason'
          description: >-
            Present if the status is `CANCELED`.

            See [ActionCancelReason](#type-actioncancelreason) for possible
            values
          readOnly: true
        created_at:
          type: string
          description: >-
            The time when the `TerminalRefund` was created, as an RFC 3339
            timestamp.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The time when the `TerminalRefund` was last updated, as an RFC 3339
            timestamp.
          readOnly: true
        app_id:
          type: string
          description: The ID of the application that created the refund.
          readOnly: true
        location_id:
          type: string
          description: The location of the device where the `TerminalRefund` was directed.
          maxLength: 64
          readOnly: true
    TerminalRefundQuery:
      type: object
      x-release-status: PUBLIC
      properties:
        filter:
          $ref: '#/components/schemas/TerminalRefundQueryFilter'
          description: The filter for the Terminal refund query.
          nullable: true
        sort:
          $ref: '#/components/schemas/TerminalRefundQuerySort'
          description: The sort order for the Terminal refund query.
          nullable: true
    TerminalRefundQueryFilter:
      type: object
      x-release-status: PUBLIC
      properties:
        device_id:
          type: string
          description: >-
            `TerminalRefund` objects associated with a specific device. If no
            device is specified, then all

            `TerminalRefund` objects for the signed-in account are displayed.
          nullable: true
        created_at:
          $ref: '#/components/schemas/TimeRange'
          description: >-
            The timestamp for the beginning of the reporting period, in RFC 3339
            format. Inclusive.

            Default value: The current time minus one day.

            Note that `TerminalRefund`s are available for 30 days after
            creation.
        status:
          type: string
          description: >-
            Filtered results with the desired status of the `TerminalRefund`.

            Options: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`,
            or `COMPLETED`.
          nullable: true
    TerminalRefundQuerySort:
      type: object
      x-release-status: PUBLIC
      properties:
        sort_order:
          type: string
          description: |-
            The order in which results are listed.
            - `ASC` - Oldest to newest.
            - `DESC` - Newest to oldest (default).
          nullable: true
    TestWebhookSubscriptionRequest:
      type: object
      description: >-
        Tests a [Subscription](entity:WebhookSubscription) by sending a test
        event to its notification URL.
      x-release-status: PUBLIC
      properties:
        event_type:
          type: string
          description: >-
            The event type that will be used to test the
            [Subscription](entity:WebhookSubscription). The event type must be

            contained in the list of event types in the
            [Subscription](entity:WebhookSubscription).
          nullable: true
      example:
        event_type: payment.created
    TestWebhookSubscriptionResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [TestWebhookSubscription](api-endpoint:WebhookSubscriptions-TestWebhookSubscription)
        endpoint.


        Note: If there are errors processing the request, the
        [SubscriptionTestResult](entity:SubscriptionTestResult) field is not

        present.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        subscription_test_result:
          $ref: '#/components/schemas/SubscriptionTestResult'
          description: The [SubscriptionTestResult](entity:SubscriptionTestResult).
      example:
        subscription_test_result:
          created_at: 2022-01-11 00:06:48.322945116 +0000 UTC m=+3863.054453746
          id: 23eed5a9-2b12-403e-b212-7e2889aea0f6
          payload: >-
            {"merchant_id":"1ZYMKZY1YFGBW","type":"payment.created","event_id":"23eed5a9-2b12-403e-b212-7e2889aea0f6","created_at":"2022-01-11T00:06:48.322945116Z","data":{"type":"payment","id":"KkAkhdMsgzn59SM8A89WgKwekxLZY","object":{"payment":{"amount_money":{"amount":100,"currency":"USD"},"approved_money":{"amount":100,"currency":"USD"},"capabilities":["EDIT_TIP_AMOUNT","EDIT_TIP_AMOUNT_UP","EDIT_TIP_AMOUNT_DOWN"],"card_details":{"avs_status":"AVS_ACCEPTED","card":{"bin":"540988","card_brand":"MASTERCARD","card_type":"CREDIT","exp_month":11,"exp_year":2022,"fingerprint":"sq-1-Tvruf3vPQxlvI6n0IcKYfBukrcv6IqWr8UyBdViWXU2yzGn5VMJvrsHMKpINMhPmVg","last_4":"9029","prepaid_type":"NOT_PREPAID"},"card_payment_timeline":{"authorized_at":"2020-11-22T21:16:51.198Z"},"cvv_status":"CVV_ACCEPTED","entry_method":"KEYED","statement_description":"SQ
            *DEFAULT TEST
            ACCOUNT","status":"AUTHORIZED"},"created_at":"2020-11-22T21:16:51.086Z","delay_action":"CANCEL","delay_duration":"PT168H","delayed_until":"2020-11-29T21:16:51.086Z","id":"hYy9pRFVxpDsO1FB05SunFWUe9JZY","location_id":"S8GWD5R9QB376","order_id":"03O3USaPaAaFnI6kkwB1JxGgBsUZY","receipt_number":"hYy9","risk_evaluation":{"created_at":"2020-11-22T21:16:51.198Z","risk_level":"NORMAL"},"source_type":"CARD","status":"APPROVED","total_money":{"amount":100,"currency":"USD"},"updated_at":"2020-11-22T21:16:51.198Z","version_token":"FfQhQJf9r3VSQIgyWBk1oqhIwiznLwVwJbVVA0bdyEv6o"}}}}
          status_code: 404
          updated_at: 2022-01-11 00:06:48.322945116 +0000 UTC m=+3863.054453746
    TimeRange:
      type: object
      description: |-
        Represents a generic time range. The start and end values are
        represented in RFC 3339 format. Time ranges are customized to be
        inclusive or exclusive based on the needs of a particular endpoint.
        Refer to the relevant endpoint-specific documentation to determine
        how time ranges are handled.
      x-release-status: PUBLIC
      properties:
        start_at:
          type: string
          description: |-
            A datetime value in RFC 3339 format indicating when the time range
            starts.
          nullable: true
        end_at:
          type: string
          description: |-
            A datetime value in RFC 3339 format indicating when the time range
            ends.
          nullable: true
    TipSettings:
      type: object
      x-release-status: PUBLIC
      properties:
        allow_tipping:
          type: boolean
          description: >-
            Indicates whether tipping is enabled for this checkout. Defaults to
            false.
          nullable: true
        separate_tip_screen:
          type: boolean
          description: >-
            Indicates whether tip options should be presented on the screen
            before presenting

            the signature screen during card payment. Defaults to false.
          nullable: true
        custom_tip_field:
          type: boolean
          description: >-
            Indicates whether custom tip amounts are allowed during the checkout
            flow. Defaults to false.
          nullable: true
        tip_percentages:
          type: array
          items:
            type: integer
          description: >-
            A list of tip percentages that should be presented during the
            checkout flow, specified as

            up to 3 non-negative integers from 0 to 100 (inclusive). Defaults to
            15, 20, and 25.
          nullable: true
        smart_tipping:
          type: boolean
          description: >-
            Enables the "Smart Tip Amounts" behavior.

            Exact tipping options depend on the region in which the Square
            seller is active.


            For payments under 10.00, in the Australia, Canada, Ireland, United
            Kingdom, and United States, tipping options are presented as no tip,
            .50, 1.00 or 2.00.


            For payment amounts of 10.00 or greater, tipping options are
            presented as the following percentages: 0%, 5%, 10%, 15%.


            If set to true, the `tip_percentages` settings is ignored.

            Defaults to false.


            To learn more about smart tipping, see [Accept Tips with the Square
            App](https://squareup.com/help/us/en/article/5069-accept-tips-with-the-square-app).
          nullable: true
    Transaction:
      type: object
      description: >-
        Represents a transaction processed with Square, either with the

        Connect API or with Square Point of Sale.


        The `tenders` field of this object lists all methods of payment used to
        pay in

        the transaction.
      x-release-status: DEPRECATED
      properties:
        id:
          type: string
          description: The transaction's unique ID, issued by Square payments servers.
          maxLength: 192
        location_id:
          type: string
          description: The ID of the transaction's associated location.
          maxLength: 50
          nullable: true
        created_at:
          type: string
          description: >-
            The timestamp for when the transaction was created, in RFC 3339
            format.
          maxLength: 32
        tenders:
          type: array
          items:
            $ref: '#/components/schemas/Tender'
          description: The tenders used to pay in the transaction.
          nullable: true
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
          description: Refunds that have been applied to any tender in the transaction.
          nullable: true
        reference_id:
          type: string
          description: >-
            If the transaction was created with the
            [Charge](api-endpoint:Transactions-Charge)

            endpoint, this value is the same as the value provided for the
            `reference_id`

            parameter in the request to that endpoint. Otherwise, it is not set.
          maxLength: 40
          nullable: true
        product:
          $ref: '#/components/schemas/TransactionProduct'
          description: >-
            The Square product that processed the transaction.

            See [TransactionProduct](#type-transactionproduct) for possible
            values
          nullable: true
        client_id:
          type: string
          description: >-
            If the transaction was created in the Square Point of Sale app, this
            value

            is the ID generated for the transaction by Square Point of Sale.


            This ID has no relationship to the transaction's canonical `id`,
            which is

            generated by Square's backend servers. This value is generated for
            bookkeeping

            purposes, in case the transaction cannot immediately be completed
            (for example,

            if the transaction is processed in offline mode).


            It is not currently possible with the Connect API to perform a
            transaction

            lookup by this value.
          maxLength: 192
          nullable: true
        shipping_address:
          $ref: '#/components/schemas/Address'
          description: The shipping address provided in the request, if any.
          nullable: true
        order_id:
          type: string
          description: >-
            The order_id is an identifier for the order associated with this
            transaction, if any.
          maxLength: 192
          nullable: true
    TransactionProduct:
      type: string
      enum:
        - REGISTER
        - EXTERNAL_API
        - BILLING
        - APPOINTMENTS
        - INVOICES
        - ONLINE_STORE
        - PAYROLL
        - OTHER
      x-enum-elements:
        - name: REGISTER
          description: Square Point of Sale.
        - name: EXTERNAL_API
          description: The Square Connect API.
        - name: BILLING
          description: A Square subscription for one of multiple products.
        - name: APPOINTMENTS
          description: Square Appointments.
        - name: INVOICES
          description: Square Invoices.
        - name: ONLINE_STORE
          description: Square Online Store.
        - name: PAYROLL
          description: Square Payroll.
        - name: OTHER
          description: A Square product that does not match any other value.
      description: Indicates the Square product used to process a transaction.
      x-release-status: DEPRECATED
    TransactionType:
      type: string
      enum:
        - DEBIT
        - CREDIT
      x-enum-elements:
        - name: DEBIT
          description: ''
        - name: CREDIT
          description: ''
      description: The transaction type used in the disputed payment.
      x-release-status: PUBLIC
    UnlinkCustomerFromGiftCardRequest:
      type: object
      description: A request to unlink a customer from a gift card.
      x-release-status: PUBLIC
      x-params-example: '?gift_card_id=gftc:71ea002277a34f8a945e284b04822edb'
      required:
        - customer_id
      properties:
        customer_id:
          type: string
          description: The ID of the customer to unlink from the gift card.
          minLength: 1
          maxLength: 191
      example:
        customer_id: GKY0FZ3V717AH8Q2D821PNT2ZW
    UnlinkCustomerFromGiftCardResponse:
      type: object
      description: >-
        A response that contains the unlinked `GiftCard` object. If the request
        resulted in errors, 

        the response contains a set of `Error` objects.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        gift_card:
          $ref: '#/components/schemas/GiftCard'
          description: >-
            The gift card with the ID of the unlinked customer removed from the
            `customer_ids` field. 

            If no other customers are linked, the `customer_ids` field is also
            removed.
      example:
        gift_card:
          balance_money:
            amount: 2500
            currency: USD
          created_at: '2021-03-25T05:13:01Z'
          gan: '7783320005440920'
          gan_source: SQUARE
          id: gftc:71ea002277a34f8a945e284b04822edb
          state: ACTIVE
          type: DIGITAL
    UpdateBookingCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents an
        [UpdateBookingCustomAttributeDefinition](api-endpoint:BookingCustomAttributes-UpdateBookingCustomAttributeDefinition)
        request.
      x-release-status: PUBLIC
      required:
        - custom_attribute_definition
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The custom attribute definition that contains the fields to update.
            Only the following fields can be updated:

            - `name`

            - `description`

            - `visibility`

            - `schema` for a `Selection` data type. Only changes to the named
            options or the maximum number of allowed

            selections are supported.


            For more information, see

            [Updatable definition
            fields](https://developer.squareup.com/docs/booking-custom-attributes-api/custom-attribute-definitions#updatable-definition-fields).


            To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control, include the optional `version` field and specify the
            current version of the custom attribute definition.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency.
            For more information,

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
          nullable: true
    UpdateBookingCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents an
        [UpdateBookingCustomAttributeDefinition](api-endpoint:BookingCustomAttributes-UpdateBookingCustomAttributeDefinition)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: PUBLIC
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The updated custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2022-11-16T15:27:30Z'
          description: Update the description as desired.
          key: favoriteShampoo
          name: Favorite shampoo
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          updated_at: '2022-11-16T15:39:38Z'
          version: 2
          visibility: VISIBILITY_READ_ONLY
        errors: []
    UpdateBookingRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - booking
      properties:
        idempotency_key:
          type: string
          description: A unique key to make this request an idempotent operation.
          maxLength: 255
          nullable: true
        booking:
          $ref: '#/components/schemas/Booking'
          description: >-
            The booking to be updated. Individual attributes explicitly
            specified here override the corresponding values of the existing
            booking.
    UpdateBookingResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        booking:
          $ref: '#/components/schemas/Booking'
          description: The booking that was updated.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors that occurred during the request.
      example:
        booking:
          address:
            address_line_1: 1955 Broadway
            address_line_2: Suite 600
            administrative_district_level_1: CA
            locality: Oakland
            postal_code: '94612'
          appointment_segments:
            - duration_minutes: 60
              service_variation_id: RU3PBTZTK7DXZDQFCJHOK2MC
              service_variation_version: 1599775456731
              team_member_id: TMXUrsBWWcHTt79t
          created_at: '2020-10-28T15:47:41Z'
          customer_id: EX2QSVGTZN4K1E5QE1CBFNVQ8M
          customer_note: I would like to sit near the window please
          id: zkras0xv0xwswx
          location_id: LEQHH0YY8B42M
          location_type: CUSTOMER_LOCATION
          seller_note: ''
          start_at: '2020-11-26T13:00:00Z'
          status: ACCEPTED
          updated_at: '2020-10-28T15:49:25Z'
          version: 2
        errors: []
    UpdateBreakTypeRequest:
      type: object
      description: A request to update a `BreakType`.
      x-release-status: PUBLIC
      required:
        - break_type
      properties:
        break_type:
          $ref: '#/components/schemas/BreakType'
          description: The updated `BreakType`.
      example:
        break_type:
          break_name: Lunch
          expected_duration: PT50M
          is_paid: true
          location_id: 26M7H24AZ9N6R
          version: 1
    UpdateBreakTypeResponse:
      type: object
      description: >-
        A response to a request to update a `BreakType`. The response contains

        the requested `BreakType` objects and might contain a set of `Error`
        objects if

        the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        break_type:
          $ref: '#/components/schemas/BreakType'
          description: The response object.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        break_type:
          break_name: Lunch
          created_at: '2018-06-12T20:19:12Z'
          expected_duration: PT50M
          id: Q6JSJS6D4DBCH
          is_paid: true
          location_id: 26M7H24AZ9N6R
          updated_at: '2019-02-26T23:12:59Z'
          version: 2
    UpdateCatalogImageRequest:
      type: object
      x-release-status: BETA
      required:
        - idempotency_key
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this UpdateCatalogImage request.

            Keys can be any valid string but must be unique for every
            UpdateCatalogImage request.


            See [Idempotency
            keys](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
            for more information.
          minLength: 1
          maxLength: 128
      example:
        idempotency_key: 528dea59-7bfb-43c1-bd48-4a6bba7dd61f86
        image:
          image_data:
            caption: A picture of a cup of coffee
            name: Coffee
          type: IMAGE
        object_id: ND6EA5AAJEO5WL3JNNIAQA32
    UpdateCatalogImageResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        image:
          $ref: '#/components/schemas/CatalogObject'
          description: |-
            The newly updated `CatalogImage` including a Square-generated
            URL for the encapsulated image file.
      example:
        image:
          id: L52QOQN2SW3M5QTF9JOCQKNB
          image_data:
            caption: A picture of a cup of coffee
            name: Coffee
            url: https://...
          type: IMAGE
    UpdateCustomerCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents an
        [UpdateCustomerCustomAttributeDefinition](api-endpoint:CustomerCustomAttributes-UpdateCustomerCustomAttributeDefinition)
        request.
      x-release-status: PUBLIC
      x-params-example: '?key=favoritemovie'
      required:
        - custom_attribute_definition
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The custom attribute definition that contains the fields to update.
            This endpoint

            supports sparse updates, so only new or changed fields need to be
            included in the request.

            Only the following fields can be updated:


            - `name`

            - `description`

            - `visibility`

            - `schema` for a `Selection` data type. Only changes to the named
            options or the maximum number of allowed

            selections are supported.


            For more information, see

            [Updatable definition
            fields](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attribute-definitions#updatable-definition-fields).


            To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency) 

            control, include the optional `version` field and specify the
            current version of the custom attribute definition.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency.
            For more information,

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
          nullable: true
      example:
        custom_attribute_definition:
          description: Update the description as desired.
          visibility: VISIBILITY_READ_ONLY
    UpdateCustomerCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents an
        [UpdateCustomerCustomAttributeDefinition](api-endpoint:CustomerCustomAttributes-UpdateCustomerCustomAttributeDefinition)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: PUBLIC
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The updated custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2022-04-26T15:27:30Z'
          description: Update the description as desired.
          key: favoritemovie
          name: Favorite Movie
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          updated_at: '2022-04-26T15:39:38Z'
          version: 2
          visibility: VISIBILITY_READ_ONLY
    UpdateCustomerGroupRequest:
      type: object
      description: >-
        Defines the body parameters that can be included in a request to the

        [UpdateCustomerGroup](api-endpoint:CustomerGroups-UpdateCustomerGroup)
        endpoint.
      x-release-status: PUBLIC
      required:
        - group
      properties:
        group:
          $ref: '#/components/schemas/CustomerGroup'
          description: >-
            The `CustomerGroup` object including all the updates you want to
            make.
      example:
        group:
          name: Loyal Customers
    UpdateCustomerGroupResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [UpdateCustomerGroup](api-endpoint:CustomerGroups-UpdateCustomerGroup)
        endpoint.


        Either `errors` or `group` is present in a given response (never both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        group:
          $ref: '#/components/schemas/CustomerGroup'
          description: The successfully updated customer group.
      example:
        group:
          created_at: '2020-04-13T21:54:57.863Z'
          id: 2TAT3CMH4Q0A9M87XJZED0WMR3
          name: Loyal Customers
          updated_at: '2020-04-13T21:54:58Z'
    UpdateCustomerRequest:
      type: object
      description: |-
        Defines the body parameters that can be included in a request to the
        `UpdateCustomer` endpoint.
      x-release-status: PUBLIC
      properties:
        given_name:
          type: string
          description: >-
            The given name (that is, the first name) associated with the
            customer profile.


            The maximum length for this value is 300 characters.
          nullable: true
        family_name:
          type: string
          description: >-
            The family name (that is, the last name) associated with the
            customer profile.


            The maximum length for this value is 300 characters.
          nullable: true
        company_name:
          type: string
          description: |-
            A business name associated with the customer profile.

            The maximum length for this value is 500 characters.
          nullable: true
        nickname:
          type: string
          description: |-
            A nickname for the customer profile.

            The maximum length for this value is 100 characters.
          nullable: true
        email_address:
          type: string
          description: |-
            The email address associated with the customer profile.

            The maximum length for this value is 254 characters.
          nullable: true
        address:
          $ref: '#/components/schemas/Address'
          description: >-
            The physical address associated with the customer profile. Only new
            or changed fields are required in the request.


            For maximum length constraints, see [Customer
            addresses](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#address).

            The `first_name` and `last_name` fields are ignored if they are
            present in the request.
          nullable: true
        phone_number:
          type: string
          description: >-
            The phone number associated with the customer profile. The phone
            number must be valid and can contain

            916 digits, with an optional `+` prefix and country code. For more
            information, see

            [Customer phone
            numbers](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#phone-number).
          nullable: true
        reference_id:
          type: string
          description: |-
            An optional second ID used to associate the customer profile with an
            entity in another system.

            The maximum length for this value is 100 characters.
          nullable: true
        note:
          type: string
          description: A custom note associated with the customer profile.
          nullable: true
        birthday:
          type: string
          description: >-
            The birthday associated with the customer profile, in `YYYY-MM-DD`
            or `MM-DD` format. For example,

            specify `1998-09-21` for September 21, 1998, or `09-21` for
            September 21. Birthdays are returned in `YYYY-MM-DD`

            format, where `YYYY` is the specified birth year or `0000` if a
            birth year is not specified.
          nullable: true
        version:
          type: integer
          description: >-
            The current version of the customer profile.


            As a best practice, you should include this field to enable
            [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)
            control. For more information, see [Update a customer
            profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#update-a-customer-profile).
          format: int64
        tax_ids:
          $ref: '#/components/schemas/CustomerTaxIds'
          description: >-
            The tax ID associated with the customer profile. This field is
            available only for customers of sellers

            in EU countries or the United Kingdom. For more information,

            see [Customer tax
            IDs](https://developer.squareup.com/docs/customers-api/what-it-does#customer-tax-ids).
          nullable: true
      example:
        email_address: New.Amelia.Earhart@example.com
        note: updated customer note
        phone_number: null
        version: 2
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/UpdateCustomer/UpdateCustomerRequest.csharp
        java: /sdk_samples/UpdateCustomer/UpdateCustomerRequest.java
        javascript: /sdk_samples/UpdateCustomer/UpdateCustomerRequest.javascript
        php: /sdk_samples/UpdateCustomer/UpdateCustomerRequest.php
        python: /sdk_samples/UpdateCustomer/UpdateCustomerRequest.python
        ruby: /sdk_samples/UpdateCustomer/UpdateCustomerRequest.ruby
    UpdateCustomerResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [UpdateCustomer](api-endpoint:Customers-UpdateCustomer)
        or

        [BulkUpdateCustomers](api-endpoint:Customers-BulkUpdateCustomers)
        endpoint.


        Either `errors` or `customer` is present in a given response (never
        both).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        customer:
          $ref: '#/components/schemas/Customer'
          description: The updated customer.
      example:
        customer:
          address:
            address_line_1: 500 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          created_at: '2016-03-23T20:21:54.859Z'
          creation_source: THIRD_PARTY
          email_address: New.Amelia.Earhart@example.com
          family_name: Earhart
          given_name: Amelia
          id: JDKYHBWT1D4F8MFH63DBMEN8Y4
          note: updated customer note
          preferences:
            email_unsubscribed: false
          reference_id: YOUR_REFERENCE_ID
          updated_at: '2016-05-15T20:21:55Z'
          version: 3
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/UpdateCustomer/UpdateCustomerResponse.csharp
        java: /sdk_samples/UpdateCustomer/UpdateCustomerResponse.java
        javascript: /sdk_samples/UpdateCustomer/UpdateCustomerResponse.javascript
        php: /sdk_samples/UpdateCustomer/UpdateCustomerResponse.php
        python: /sdk_samples/UpdateCustomer/UpdateCustomerResponse.python
        ruby: /sdk_samples/UpdateCustomer/UpdateCustomerResponse.ruby
    UpdateInvoiceRequest:
      type: object
      description: Describes a `UpdateInvoice` request.
      x-release-status: PUBLIC
      required:
        - invoice
      properties:
        invoice:
          $ref: '#/components/schemas/Invoice'
          description: >-
            The invoice fields to add, change, or clear. Fields can be cleared
            using

            null values or the `remove` field (for individual payment requests
            or reminders).

            The current invoice `version` is also required. For more
            information, including requirements,

            limitations, and more examples, see [Update an
            Invoice](https://developer.squareup.com/docs/invoices-api/update-invoices).
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies the `UpdateInvoice` request. If you
            do not

            provide `idempotency_key` (or provide an empty string as the value),
            the endpoint

            treats each request as independent.


            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 128
          nullable: true
        fields_to_clear:
          type: array
          items:
            type: string
          description: >-
            The list of fields to clear. Although this field is currently
            supported, we

            recommend using null values or the `remove` field when possible. For
            examples, see

            [Update an
            Invoice](https://developer.squareup.com/docs/invoices-api/update-invoices).
          nullable: true
      example:
        idempotency_key: 4ee82288-0910-499e-ab4c-5d0071dad1be
        invoice:
          payment_requests:
            - reminders: null
              tipping_enabled: false
              uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355
          version: 1
    UpdateInvoiceResponse:
      type: object
      description: Describes a `UpdateInvoice` response.
      x-release-status: PUBLIC
      properties:
        invoice:
          $ref: '#/components/schemas/Invoice'
          description: The updated invoice.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
      example:
        invoice:
          accepted_payment_methods:
            bank_account: false
            buy_now_pay_later: false
            card: true
            cash_app_pay: false
            square_gift_card: false
          created_at: '2020-06-18T17:45:13Z'
          custom_fields:
            - label: Event Reference Number
              placement: ABOVE_LINE_ITEMS
              value: 'Ref. #1234'
            - label: Terms of Service
              placement: BELOW_LINE_ITEMS
              value: The terms of service are...
          delivery_method: EMAIL
          description: We appreciate your business!
          id: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY
          invoice_number: inv-100
          location_id: ES0RJRZYEC39A
          next_payment_amount_money:
            amount: 10000
            currency: USD
          order_id: CAISENgvlJ6jLWAzERDzjyHVybY
          payment_requests:
            - automatic_payment_source: NONE
              computed_amount_money:
                amount: 10000
                currency: USD
              due_date: '2030-01-24'
              request_type: BALANCE
              tipping_enabled: false
              total_completed_amount_money:
                amount: 0
                currency: USD
              uid: 2da7964f-f3d2-4f43-81e8-5aa220bf3355
          primary_recipient:
            customer_id: JDKYHBWT1D4F8MFH63DBMEN8Y4
            email_address: Amelia.Earhart@example.com
            family_name: Earhart
            given_name: Amelia
            phone_number: 1-212-555-4240
          sale_or_service_date: '2030-01-24'
          scheduled_at: '2030-01-13T10:00:00Z'
          status: UNPAID
          store_payment_method_enabled: false
          timezone: America/Los_Angeles
          title: Event Planning Services
          updated_at: '2020-06-18T18:23:11Z'
          version: 2
    UpdateItemModifierListsRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - item_ids
      properties:
        item_ids:
          type: array
          items:
            type: string
          description: >-
            The IDs of the catalog items associated with the CatalogModifierList
            objects being updated.
        modifier_lists_to_enable:
          type: array
          items:
            type: string
          description: >-
            The IDs of the CatalogModifierList objects to enable for the
            CatalogItem.

            At least one of `modifier_lists_to_enable` or
            `modifier_lists_to_disable` must be specified.
          nullable: true
        modifier_lists_to_disable:
          type: array
          items:
            type: string
          description: >-
            The IDs of the CatalogModifierList objects to disable for the
            CatalogItem.

            At least one of `modifier_lists_to_enable` or
            `modifier_lists_to_disable` must be specified.
          nullable: true
      example:
        item_ids:
          - H42BRLUJ5KTZTTMPVSLFAACQ
          - 2JXOBJIHCWBQ4NZ3RIXQGJA6
        modifier_lists_to_disable:
          - 7WRC16CJZDVLSNDQ35PP6YAD
        modifier_lists_to_enable:
          - H42BRLUJ5KTZTTMPVSLFAACQ
          - 2JXOBJIHCWBQ4NZ3RIXQGJA6
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/UpdateItemModifierLists/UpdateItemModifierListsRequest.csharp
        java: >-
          /sdk_samples/Catalog/UpdateItemModifierLists/UpdateItemModifierListsRequest.java
        javascript: >-
          /sdk_samples/Catalog/UpdateItemModifierLists/UpdateItemModifierListsRequest.javascript
        php: >-
          /sdk_samples/Catalog/UpdateItemModifierLists/UpdateItemModifierListsRequest.php
        python: >-
          /sdk_samples/Catalog/UpdateItemModifierLists/UpdateItemModifierListsRequest.python
        ruby: >-
          /sdk_samples/Catalog/UpdateItemModifierLists/UpdateItemModifierListsRequest.ruby
    UpdateItemModifierListsResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        updated_at:
          type: string
          description: >-
            The database
            [timestamp](https://developer.squareup.com/docs/build-basics/common-data-types/working-with-dates)
            of this update in RFC 3339 format, e.g., `2016-09-04T23:59:33.123Z`.
      example:
        updated_at: '2016-11-16T22:25:24.878Z'
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/UpdateItemModifierLists/UpdateItemModifierListsResponse.csharp
        java: >-
          /sdk_samples/Catalog/UpdateItemModifierLists/UpdateItemModifierListsResponse.java
        javascript: >-
          /sdk_samples/Catalog/UpdateItemModifierLists/UpdateItemModifierListsResponse.javascript
        php: >-
          /sdk_samples/Catalog/UpdateItemModifierLists/UpdateItemModifierListsResponse.php
        python: >-
          /sdk_samples/Catalog/UpdateItemModifierLists/UpdateItemModifierListsResponse.python
        ruby: >-
          /sdk_samples/Catalog/UpdateItemModifierLists/UpdateItemModifierListsResponse.ruby
    UpdateItemTaxesRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - item_ids
      properties:
        item_ids:
          type: array
          items:
            type: string
          description: >-
            IDs for the CatalogItems associated with the CatalogTax objects
            being updated.

            No more than 1,000 IDs may be provided.
        taxes_to_enable:
          type: array
          items:
            type: string
          description: >-
            IDs of the CatalogTax objects to enable.

            At least one of `taxes_to_enable` or `taxes_to_disable` must be
            specified.
          nullable: true
        taxes_to_disable:
          type: array
          items:
            type: string
          description: >-
            IDs of the CatalogTax objects to disable.

            At least one of `taxes_to_enable` or `taxes_to_disable` must be
            specified.
          nullable: true
      example:
        item_ids:
          - H42BRLUJ5KTZTTMPVSLFAACQ
          - 2JXOBJIHCWBQ4NZ3RIXQGJA6
        taxes_to_disable:
          - AQCEGCEBBQONINDOHRGZISEX
        taxes_to_enable:
          - 4WRCNHCJZDVLSNDQ35PP6YAD
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/Catalog/UpdateItemTaxes/UpdateItemTaxesRequest.csharp
        java: /sdk_samples/Catalog/UpdateItemTaxes/UpdateItemTaxesRequest.java
        javascript: /sdk_samples/Catalog/UpdateItemTaxes/UpdateItemTaxesRequest.javascript
        php: /sdk_samples/Catalog/UpdateItemTaxes/UpdateItemTaxesRequest.php
        python: /sdk_samples/Catalog/UpdateItemTaxes/UpdateItemTaxesRequest.python
        ruby: /sdk_samples/Catalog/UpdateItemTaxes/UpdateItemTaxesRequest.ruby
    UpdateItemTaxesResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        updated_at:
          type: string
          description: >-
            The database
            [timestamp](https://developer.squareup.com/docs/build-basics/working-with-dates)
            of this update in RFC 3339 format, e.g., `2016-09-04T23:59:33.123Z`.
      example:
        updated_at: '2016-11-16T22:25:24.878Z'
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/Catalog/UpdateItemTaxes/UpdateItemTaxesResponse.csharp
        java: /sdk_samples/Catalog/UpdateItemTaxes/UpdateItemTaxesResponse.java
        javascript: >-
          /sdk_samples/Catalog/UpdateItemTaxes/UpdateItemTaxesResponse.javascript
        php: /sdk_samples/Catalog/UpdateItemTaxes/UpdateItemTaxesResponse.php
        python: /sdk_samples/Catalog/UpdateItemTaxes/UpdateItemTaxesResponse.python
        ruby: /sdk_samples/Catalog/UpdateItemTaxes/UpdateItemTaxesResponse.ruby
    UpdateJobRequest:
      type: object
      description: Represents an [UpdateJob](api-endpoint:Team-UpdateJob) request.
      x-release-status: BETA
      required:
        - job
      properties:
        job:
          $ref: '#/components/schemas/Job'
          description: >-
            The job with the updated fields, either `title`, `is_tip_eligible`,
            or both. Only changed fields need

            to be included in the request. Optionally include `version` to
            enable optimistic concurrency control.
      example:
        job:
          is_tip_eligible: true
          title: Cashier 1
    UpdateJobResponse:
      type: object
      description: >-
        Represents an [UpdateJob](api-endpoint:Team-UpdateJob) response. Either
        `job` or `errors`

        is present in the response.
      x-release-status: BETA
      properties:
        job:
          $ref: '#/components/schemas/Job'
          description: The updated job.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: The errors that occurred during the request.
      example:
        job:
          created_at: '2021-06-11T22:55:45Z'
          id: 1yJlHapkseYnNPETIU1B
          is_tip_eligible: true
          title: Cashier 1
          updated_at: '2021-06-13T12:55:45Z'
          version: 2
    UpdateLocationCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents an
        [UpdateLocationCustomAttributeDefinition](api-endpoint:LocationCustomAttributes-UpdateLocationCustomAttributeDefinition)
        request.
      x-release-status: BETA
      x-params-example: '?key=bestseller'
      required:
        - custom_attribute_definition
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The custom attribute definition that contains the fields to update.
            This endpoint

            supports sparse updates, so only new or changed fields need to be
            included in the request.

            Only the following fields can be updated:

            - `name`

            - `description`

            - `visibility`

            - `schema` for a `Selection` data type. Only changes to the named
            options or the maximum number of allowed

            selections are supported.


            For more information, see

            [Update a location custom attribute
            definition](https://developer.squareup.com/docs/location-custom-attributes-api/custom-attribute-definitions#update-custom-attribute-definition).

            To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control, specify the current version of the custom attribute
            definition. 

            If this is not important for your application, `version` can be set
            to -1.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency.
            For more information,

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
          nullable: true
      example:
        custom_attribute_definition:
          description: Update the description as desired.
          visibility: VISIBILITY_READ_ONLY
    UpdateLocationCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents an
        [UpdateLocationCustomAttributeDefinition](api-endpoint:LocationCustomAttributes-UpdateLocationCustomAttributeDefinition)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: BETA
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The updated custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2022-12-02T19:06:36.559Z'
          description: Update the description as desired.
          key: bestseller
          name: Bestseller
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          updated_at: '2022-12-02T19:34:10.181Z'
          version: 2
          visibility: VISIBILITY_READ_ONLY
    UpdateLocationRequest:
      type: object
      description: >-
        The request object for the
        [UpdateLocation](api-endpoint:Locations-UpdateLocation) endpoint.
      x-release-status: PUBLIC
      properties:
        location:
          $ref: '#/components/schemas/Location'
          description: The `Location` object with only the fields to update.
          nullable: true
      example:
        location:
          business_hours:
            periods:
              - day_of_week: FRI
                end_local_time: '18:00'
                start_local_time: '07:00'
              - day_of_week: SAT
                end_local_time: '18:00'
                start_local_time: '07:00'
              - day_of_week: SUN
                end_local_time: '15:00'
                start_local_time: '09:00'
          description: Midtown Atlanta store - Open weekends
    UpdateLocationResponse:
      type: object
      description: >-
        The response object returned by the
        [UpdateLocation](api-endpoint:Locations-UpdateLocation) endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information about errors encountered during the request.
        location:
          $ref: '#/components/schemas/Location'
          description: The updated `Location` object.
      example:
        location:
          address:
            address_line_1: 1234 Peachtree St. NE
            administrative_district_level_1: GA
            locality: Atlanta
            postal_code: '30309'
          business_hours:
            periods:
              - day_of_week: FRI
                end_local_time: '18:00'
                start_local_time: '07:00'
              - day_of_week: SAT
                end_local_time: '18:00'
                start_local_time: '07:00'
              - day_of_week: SUN
                end_local_time: '15:00'
                start_local_time: '09:00'
          business_name: Jet Fuel Coffee
          capabilities:
            - CREDIT_CARD_PROCESSING
          coordinates:
            latitude: 33.7889
            longitude: -84.3841
          country: US
          created_at: '2022-02-19T17:58:25Z'
          currency: USD
          description: Midtown Atlanta store - Open weekends
          id: 3Z4V4WHQK64X9
          language_code: en-US
          mcc: '7299'
          merchant_id: 3MYCJG5GVYQ8Q
          name: Midtown
          status: ACTIVE
          timezone: America/New_York
          type: PHYSICAL
    UpdateLocationSettingsRequest:
      type: object
      x-release-status: BETA
      required:
        - location_settings
      properties:
        location_settings:
          $ref: '#/components/schemas/CheckoutLocationSettings'
          description: >-
            Describe your updates using the `location_settings` object. Make
            sure it contains only the fields that have changed.
    UpdateLocationSettingsResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred when updating the location settings.
        location_settings:
          $ref: '#/components/schemas/CheckoutLocationSettings'
          description: The updated location settings.
      example:
        location_settings:
          branding:
            button_color: '#00b23b'
            button_shape: ROUNDED
            header_type: FRAMED_LOGO
          customer_notes_enabled: false
          location_id: LOCATION_ID_1
          policies:
            - description: This is my Return Policy
              title: Return Policy
              uid: POLICY_ID_1
            - description: Items may be returned within 30 days of purchase.
              title: Return Policy
              uid: POLICY_ID_2
          tipping:
            default_percent: 20
            default_whole_amount_money:
              amount: 100
              currency: USD
            percentages:
              - 15
              - 20
              - 25
            smart_tipping_enabled: true
            whole_amounts:
              - amount: 1000
                currency: USD
              - amount: 1500
                currency: USD
              - amount: 2000
                currency: USD
          updated_at: '2022-06-16T22:25:35Z'
    UpdateMerchantCustomAttributeDefinitionRequest:
      type: object
      description: >-
        Represents an
        [UpdateMerchantCustomAttributeDefinition](api-endpoint:MerchantCustomAttributes-UpdateMerchantCustomAttributeDefinition)
        request.
      x-release-status: BETA
      x-params-example: '?key=alternative_seller_name'
      required:
        - custom_attribute_definition
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The custom attribute definition that contains the fields to update.
            This endpoint

            supports sparse updates, so only new or changed fields need to be
            included in the request.

            Only the following fields can be updated:

            - `name`

            - `description`

            - `visibility`

            - `schema` for a `Selection` data type. Only changes to the named
            options or the maximum number of allowed

            selections are supported.

            For more information, see

            [Update a merchant custom attribute
            definition](https://developer.squareup.com/docs/merchant-custom-attributes-api/custom-attribute-definitions#update-custom-attribute-definition).

            The version field must match the current version of the custom
            attribute definition to enable

            [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            If this is not important for your application, version can be set to
            -1. For any other values, the request fails with a BAD_REQUEST
            error.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency.
            For more information,

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
          nullable: true
      example:
        custom_attribute_definition:
          description: Update the description as desired.
          visibility: VISIBILITY_READ_ONLY
    UpdateMerchantCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents an
        [UpdateMerchantCustomAttributeDefinition](api-endpoint:MerchantCustomAttributes-UpdateMerchantCustomAttributeDefinition)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: BETA
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The updated custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2023-05-05T19:06:36.559Z'
          description: Update the description as desired.
          key: alternative_seller_name
          name: Alternative Merchant Name
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String
          updated_at: '2023-05-05T19:34:10.181Z'
          version: 2
          visibility: VISIBILITY_READ_ONLY
    UpdateMerchantSettingsRequest:
      type: object
      x-release-status: BETA
      required:
        - merchant_settings
      properties:
        merchant_settings:
          $ref: '#/components/schemas/CheckoutMerchantSettings'
          description: >-
            Describe your updates using the `merchant_settings` object. Make
            sure it contains only the fields that have changed.
    UpdateMerchantSettingsResponse:
      type: object
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred when updating the merchant settings.
        merchant_settings:
          $ref: '#/components/schemas/CheckoutMerchantSettings'
          description: The updated merchant settings.
      example:
        merchant_settings:
          merchant_id: MERCHANT_ID
          payment_methods:
            afterpay_clearpay:
              enabled: true
              item_eligibility_range:
                max:
                  amount: 10000
                  currency: USD
                min:
                  amount: 100
                  currency: USD
              order_eligibility_range:
                max:
                  amount: 10000
                  currency: USD
                min:
                  amount: 100
                  currency: USD
            apple_pay:
              enabled: false
            cash_app_pay:
              enabled: true
            google_pay:
              enabled: true
          updated_at: '2022-06-16T22:25:35Z'
    UpdateOrderCustomAttributeDefinitionRequest:
      type: object
      description: Represents an update request for an order custom attribute definition.
      x-release-status: BETA
      x-params-example: '?key=cover-count'
      required:
        - custom_attribute_definition
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: >-
            The custom attribute definition that contains the fields to update.
            This endpoint supports sparse updates, 

            so only new or changed fields need to be included in the request. 
            For more information, see 

            [Updatable definition
            fields](https://developer.squareup.com/docs/orders-custom-attributes-api/custom-attribute-definitions#updatable-definition-fields).


            To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)
            control, include the optional `version` field and specify the
            current version of the custom attribute definition.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency. 

            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          minLength: 1
          maxLength: 45
          nullable: true
      example:
        custom_attribute_definition:
          key: cover-count
          version: 1
          visibility: VISIBILITY_READ_ONLY
        idempotency_key: IDEMPOTENCY_KEY
    UpdateOrderCustomAttributeDefinitionResponse:
      type: object
      description: >-
        Represents a response from updating an order custom attribute
        definition.
      x-release-status: BETA
      properties:
        custom_attribute_definition:
          $ref: '#/components/schemas/CustomAttributeDefinition'
          description: The updated order custom attribute definition.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute_definition:
          created_at: '2022-11-16T16:53:23.141Z'
          description: The number of people seated at a table
          key: cover-count
          name: Cover count
          schema:
            $ref: >-
              https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number
          updated_at: '2022-11-16T17:44:11.436Z'
          version: 2
          visibility: VISIBILITY_READ_ONLY
    UpdateOrderRequest:
      type: object
      description: |-
        Defines the fields that are included in requests to the
        [UpdateOrder](api-endpoint:Orders-UpdateOrder) endpoint.
      x-release-status: BETA
      properties:
        order:
          $ref: '#/components/schemas/Order'
          description: >-
            The [sparse
            order](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#sparse-order-objects)

            containing only the fields to update and the version to which the
            update is

            being applied.
          nullable: true
        fields_to_clear:
          type: array
          items:
            type: string
          description: >-
            The [dot notation
            paths](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#identifying-fields-to-delete)

            fields to clear. For example, `line_items[uid].note`.

            For more information, see [Deleting
            fields](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#deleting-fields).
          nullable: true
        idempotency_key:
          type: string
          description: >-
            A value you specify that uniquely identifies this update request.


            If you are unsure whether a particular update was applied to an
            order successfully,

            you can reattempt it with the same idempotency key without

            worrying about creating duplicate updates to the order.

            The latest order version is returned.


            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 192
          nullable: true
      example:
        fields_to_clear:
          - discounts
        idempotency_key: UNIQUE_STRING
        order:
          line_items:
            - base_price_money:
                amount: 200
                currency: USD
              name: COOKIE
              quantity: '2'
              uid: cookie_uid
          version: 1
    UpdateOrderResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the [UpdateOrder](api-endpoint:Orders-UpdateOrder)
        endpoint.
      x-release-status: BETA
      properties:
        order:
          $ref: '#/components/schemas/Order'
          description: The updated order.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        order:
          created_at: '2019-08-23T18:26:18.243Z'
          id: DREk7wJcyXNHqULq8JJ2iPAsluJZY
          line_items:
            - base_price_money:
                amount: 500
                currency: USD
              gross_sales_money:
                amount: 500
                currency: USD
              name: Small Coffee
              quantity: '1'
              total_discount_money:
                amount: 0
                currency: USD
              total_money:
                amount: 500
                currency: USD
              total_service_charge_money:
                amount: 0
                currency: USD
              total_tax_money:
                amount: 0
                currency: USD
              uid: EuYkakhmu3ksHIds5Hiot
              variation_total_price_money:
                amount: 500
                currency: USD
            - base_price_money:
                amount: 200
                currency: USD
              gross_sales_money:
                amount: 400
                currency: USD
              name: COOKIE
              quantity: '2'
              total_discount_money:
                amount: 0
                currency: USD
              total_money:
                amount: 400
                currency: USD
              total_service_charge_money:
                amount: 0
                currency: USD
              total_tax_money:
                amount: 0
                currency: USD
              uid: cookie_uid
              variation_total_price_money:
                amount: 400
                currency: USD
          location_id: MXVQSVNDGN3C8
          net_amounts:
            discount_money:
              amount: 0
              currency: USD
            service_charge_money:
              amount: 0
              currency: USD
            tax_money:
              amount: 0
              currency: USD
            total_money:
              amount: 900
              currency: USD
          source:
            name: Cookies
          state: OPEN
          total_discount_money:
            amount: 0
            currency: USD
          total_money:
            amount: 900
            currency: USD
          total_service_charge_money:
            amount: 0
            currency: USD
          total_tax_money:
            amount: 0
            currency: USD
          updated_at: '2019-08-23T18:33:47.523Z'
          version: 2
    UpdatePaymentLinkRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - payment_link
      properties:
        payment_link:
          $ref: '#/components/schemas/PaymentLink'
          description: >-
            The `payment_link` object describing the updates to apply.

            For more information, see [Update a payment
            link](https://developer.squareup.com/docs/checkout-api/manage-checkout#update-a-payment-link).
      example:
        payment_link:
          checkout_options:
            ask_for_shipping_address: true
          version: 1
    UpdatePaymentLinkResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred when updating the payment link.
        payment_link:
          $ref: '#/components/schemas/PaymentLink'
          description: The updated payment link.
      example:
        payment_link:
          checkout_options:
            ask_for_shipping_address: true
          created_at: '2022-04-26T00:15:15Z'
          id: TY4BWEDJ6AI5MBIV
          long_url: https://checkout.square.site/EXAMPLE
          order_id: Qqc8ypQGvxVwc46Cch4zHTaJqc4F
          payment_note: test
          updated_at: '2022-04-26T00:18:24Z'
          url: https://square.link/u/EXAMPLE
          version: 2
    UpdatePaymentRequest:
      type: object
      description: |-
        Describes a request to update a payment using
        [UpdatePayment](api-endpoint:Payments-UpdatePayment).
      x-release-status: PUBLIC
      required:
        - idempotency_key
      properties:
        payment:
          $ref: '#/components/schemas/Payment'
          description: The updated `Payment` object.
          nullable: true
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies this `UpdatePayment` request. Keys
            can be any valid string

            but must be unique for every `UpdatePayment` request.


            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          minLength: 1
          maxLength: 45
      example:
        idempotency_key: 956f8b13-e4ec-45d6-85e8-d1d95ef0c5de
        payment:
          amount_money:
            amount: 1000
            currency: USD
          tip_money:
            amount: 100
            currency: USD
          version_token: ODhwVQ35xwlzRuoZEwKXucfu7583sPTzK48c5zoGd0g6o
    UpdatePaymentResponse:
      type: object
      description: |-
        Defines the response returned by
        [UpdatePayment](api-endpoint:Payments-UpdatePayment).
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        payment:
          $ref: '#/components/schemas/Payment'
          description: The updated payment.
      example:
        payment:
          amount_money:
            amount: 1000
            currency: USD
          application_details:
            application_id: sq0ids-TcgftTEtKxJTRF1lCFJ9TA
            square_product: ECOMMERCE_API
          approved_money:
            amount: 1000
            currency: USD
          capabilities:
            - EDIT_AMOUNT_UP
            - EDIT_AMOUNT_DOWN
            - EDIT_TIP_AMOUNT_UP
            - EDIT_TIP_AMOUNT_DOWN
          card_details:
            auth_result_code: 68aLBM
            avs_status: AVS_ACCEPTED
            card:
              bin: '411111'
              card_brand: VISA
              card_type: DEBIT
              exp_month: 11
              exp_year: 2022
              fingerprint: >-
                sq-1-Hxim77tbdcbGejOejnoAklBVJed2YFLTmirfl8Q5XZzObTc8qY_U8RkwzoNL8dCEcQ
              last_4: '1111'
              prepaid_type: NOT_PREPAID
            card_payment_timeline:
              authorized_at: '2021-10-13T20:26:44.364Z'
            cvv_status: CVV_ACCEPTED
            entry_method: ON_FILE
            statement_description: SQ *EXAMPLE TEST GOSQ.C
            status: AUTHORIZED
          created_at: '2021-10-13T20:26:44.191Z'
          customer_id: W92WH6P11H4Z77CTET0RNTGFW8
          delay_action: CANCEL
          delay_duration: PT168H
          delayed_until: '2021-10-20T20:26:44.191Z'
          id: 1QjqpBVyrI9S4H9sTGDWU9JeiWdZY
          location_id: L88917AVBK2S5
          note: Example Note
          order_id: nUSN9TdxpiK3SrQg3wzmf6r8LP9YY
          receipt_number: 1Qjq
          risk_evaluation:
            created_at: '2021-10-13T20:26:45.271Z'
            risk_level: NORMAL
          source_type: CARD
          status: APPROVED
          tip_money:
            amount: 100
            currency: USD
          total_money:
            amount: 1100
            currency: USD
          updated_at: '2021-10-13T20:26:44.364Z'
          version_token: rDrXnqiS7fJgexccgdpzmwqTiXui1aIKCp9EchZ7trE6o
    UpdateShiftRequest:
      type: object
      description: A request to update a `Shift` object.
      x-release-status: PUBLIC
      required:
        - shift
      properties:
        shift:
          $ref: '#/components/schemas/Shift'
          description: The updated `Shift` object.
      example:
        shift:
          breaks:
            - break_type_id: REGS1EQR1TPZ5
              end_at: '2019-01-25T06:16:00-05:00'
              expected_duration: PT5M
              id: X7GAQYVVRRG6P
              is_paid: true
              name: Tea Break
              start_at: '2019-01-25T06:11:00-05:00'
          declared_cash_tip_money:
            amount: 500
            currency: USD
          end_at: '2019-01-25T13:11:00-05:00'
          location_id: PAA1RJZZKXBFG
          start_at: '2019-01-25T03:11:00-05:00'
          team_member_id: ormj0jJJZ5OZIzxrZYJI
          version: 1
          wage:
            hourly_rate:
              amount: 1500
              currency: USD
            tip_eligible: true
            title: Bartender
    UpdateShiftResponse:
      type: object
      description: |-
        The response to a request to update a `Shift`. The response contains
        the updated `Shift` object and might contain a set of `Error` objects if
        the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        shift:
          $ref: '#/components/schemas/Shift'
          description: The updated `Shift`.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        shift:
          breaks:
            - break_type_id: REGS1EQR1TPZ5
              end_at: '2019-01-25T06:16:00-05:00'
              expected_duration: PT5M
              id: X7GAQYVVRRG6P
              is_paid: true
              name: Tea Break
              start_at: '2019-01-25T06:11:00-05:00'
          created_at: '2019-02-28T00:39:02Z'
          declared_cash_tip_money:
            amount: 500
            currency: USD
          employee_id: ormj0jJJZ5OZIzxrZYJI
          end_at: '2019-01-25T13:11:00-05:00'
          id: K0YH4CV5462JB
          location_id: PAA1RJZZKXBFG
          start_at: '2019-01-25T03:11:00-05:00'
          status: CLOSED
          team_member_id: ormj0jJJZ5OZIzxrZYJI
          timezone: America/New_York
          updated_at: '2019-02-28T00:42:41Z'
          version: 2
          wage:
            hourly_rate:
              amount: 1500
              currency: USD
            job_id: dZtrPh5GSDGugyXGByesVp51
            tip_eligible: true
            title: Bartender
    UpdateSubscriptionRequest:
      type: object
      description: >-
        Defines input parameters in a request to the 

        [UpdateSubscription](api-endpoint:Subscriptions-UpdateSubscription)
        endpoint.
      x-release-status: PUBLIC
      properties:
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: >-
            The subscription object containing the current version, and fields
            to update.

            Unset fields will be left at their current server values, and JSON
            `null` values will

            be treated as a request to clear the relevant data.
          nullable: true
      example:
        subscription:
          canceled_date: null
          card_id: '{NEW CARD ID}'
    UpdateSubscriptionResponse:
      type: object
      description: >-
        Defines output parameters in a response from the

        [UpdateSubscription](api-endpoint:Subscriptions-UpdateSubscription)
        endpoint.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors encountered during the request.
        subscription:
          $ref: '#/components/schemas/Subscription'
          description: The updated subscription.
      example:
        subscription:
          card_id: '{NEW CARD ID}'
          charged_through_date: '2023-03-13'
          created_at: '2023-01-30T19:27:32Z'
          customer_id: AM69AB81FT4479YH9HGWS1HZY8
          id: 7217d8ca-1fee-4446-a9e5-8540b5d8c9bb
          invoice_ids:
            - inv:0-ChAPSfVYvNewckgf3x4iigN_ENMM
            - inv:0-ChBQaCCLfjcm9WEUBGxvuydJENMM
          location_id: LPJKHYR7WFDKN
          plan_variation_id: XOUNEKCE6NSXQW5NTSQ73MMX
          source:
            name: My Application
          start_date: '2023-01-30'
          status: ACTIVE
          timezone: UTC
          version: 3
    UpdateTeamMemberRequest:
      type: object
      description: Represents an update request for a `TeamMember` object.
      x-release-status: PUBLIC
      properties:
        team_member:
          $ref: '#/components/schemas/TeamMember'
          description: >-
            The team member fields to add, change, or clear. Fields can be
            cleared using a null value. To update

            `wage_setting.job_assignments`, you must provide the complete list
            of job assignments. If needed, call

            [ListJobs](api-endpoint:Team-ListJobs) to get the required `job_id`
            values.
          nullable: true
      example:
        team_member:
          assigned_locations:
            assignment_type: EXPLICIT_LOCATIONS
            location_ids:
              - YSGH2WBKG94QZ
              - GA2Y9HSJ8KRYT
            wage_setting:
              is_overtime_exempt: true
              job_assignments:
                - annual_rate:
                    amount: 3000000
                    currency: USD
                  job_id: FjS8x95cqHiMenw4f1NAUH4P
                  pay_type: SALARY
                  weekly_hours: 40
                - hourly_rate:
                    amount: 1200
                    currency: USD
                  job_id: VDNpRv8da51NU8qZFC5zDWpF
                  pay_type: HOURLY
          email_address: joe_doe@gmail.com
          family_name: Doe
          given_name: Joe
          phone_number: '+14159283333'
          reference_id: reference_id_1
          status: ACTIVE
    UpdateTeamMemberResponse:
      type: object
      description: >-
        Represents a response from an update request containing the updated
        `TeamMember` object or error messages.
      x-release-status: PUBLIC
      properties:
        team_member:
          $ref: '#/components/schemas/TeamMember'
          description: The successfully updated `TeamMember` object.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: The errors that occurred during the request.
      example:
        team_member:
          assigned_locations:
            assignment_type: EXPLICIT_LOCATIONS
            location_ids:
              - GA2Y9HSJ8KRYT
              - YSGH2WBKG94QZ
          created_at: '2021-06-11T22:55:45Z'
          email_address: joe_doe@example.com
          family_name: Doe
          given_name: Joe
          id: 1yJlHapkseYnNPETIU1B
          is_owner: false
          phone_number: '+14159283333'
          reference_id: reference_id_1
          status: ACTIVE
          updated_at: '2021-06-15T17:38:05Z'
          wage_setting:
            created_at: '2021-06-11T22:55:45Z'
            is_overtime_exempt: true
            job_assignments:
              - annual_rate:
                  amount: 3000000
                  currency: USD
                hourly_rate:
                  amount: 1443
                  currency: USD
                job_id: FjS8x95cqHiMenw4f1NAUH4P
                job_title: Manager
                pay_type: SALARY
                weekly_hours: 40
              - hourly_rate:
                  amount: 1200
                  currency: USD
                job_id: VDNpRv8da51NU8qZFC5zDWpF
                job_title: Cashier
                pay_type: HOURLY
            team_member_id: 1yJlHapkseYnNPETIU1B
            updated_at: '2021-06-11T22:55:45Z'
            version: 1
    UpdateVendorRequest:
      type: object
      description: >-
        Represents an input to a call to
        [UpdateVendor](api-endpoint:Vendors-UpdateVendor).
      x-release-status: BETA
      required:
        - vendor
      properties:
        idempotency_key:
          type: string
          description: >-
            A client-supplied, universally unique identifier (UUID) for the

            request.


            See
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
            in the

            [API Development
            101](https://developer.squareup.com/docs/buildbasics) section for
            more

            information.
          maxLength: 128
          nullable: true
        vendor:
          $ref: '#/components/schemas/Vendor'
          description: The specified [Vendor](entity:Vendor) to be updated.
      example:
        idempotency_key: 8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe
        vendor:
          id: INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4
          name: Jack's Chicken Shack
          status: ACTIVE
          version: 1
    UpdateVendorResponse:
      type: object
      description: >-
        Represents an output from a call to
        [UpdateVendor](api-endpoint:Vendors-UpdateVendor).
      x-release-status: BETA
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Errors occurred when the request fails.
        vendor:
          $ref: '#/components/schemas/Vendor'
          description: The [Vendor](entity:Vendor) that has been updated.
      example:
        vendor:
          account_number: '4025391'
          address:
            address_line_1: 505 Electric Ave
            address_line_2: Suite 600
            administrative_district_level_1: NY
            country: US
            locality: New York
            postal_code: '10003'
          contacts:
            - email_address: joe@joesfreshseafood.com
              id: INV_VC_FMCYHBWT1TPL8MFH52PBMEN92A
              name: Joe Burrow
              ordinal: 0
              phone_number: 1-212-555-4250
          created_at: '2022-03-16T10:21:54.859Z'
          id: INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4
          name: Jack's Chicken Shack
          status: ACTIVE
          updated_at: '2022-03-16T20:21:54.859Z'
          version: 2
    UpdateWageSettingRequest:
      type: object
      description: >-
        Represents an update request for the `WageSetting` object describing a
        `TeamMember`.
      x-release-status: PUBLIC
      required:
        - wage_setting
      properties:
        wage_setting:
          $ref: '#/components/schemas/WageSetting'
          description: >-
            The complete `WageSetting` object. For all job assignments, specify
            one of the following:

            - `job_id` (recommended) - If needed, call
            [ListJobs](api-endpoint:Team-ListJobs) to get a list of all jobs.

            Requires Square API version 2024-12-18 or later.

            - `job_title` - Use the exact, case-sensitive spelling of an
            existing title unless you want to create a new job.

            This value is ignored if `job_id` is also provided.
      example:
        wage_setting:
          is_overtime_exempt: true
          job_assignments:
            - annual_rate:
                amount: 3000000
                currency: USD
              job_title: Manager
              pay_type: SALARY
              weekly_hours: 40
            - hourly_rate:
                amount: 2000
                currency: USD
              job_title: Cashier
              pay_type: HOURLY
    UpdateWageSettingResponse:
      type: object
      description: >-
        Represents a response from an update request containing the updated
        `WageSetting` object

        or error messages.
      x-release-status: PUBLIC
      properties:
        wage_setting:
          $ref: '#/components/schemas/WageSetting'
          description: The successfully updated `WageSetting` object.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: The errors that occurred during the request.
      example:
        wage_setting:
          created_at: '2019-07-10T17:26:48+00:00'
          is_overtime_exempt: true
          job_assignments:
            - annual_rate:
                amount: 3000000
                currency: USD
              hourly_rate:
                amount: 1443
                currency: USD
              job_title: Manager
              pay_type: SALARY
              weekly_hours: 40
            - hourly_rate:
                amount: 2000
                currency: USD
              job_title: Cashier
              pay_type: HOURLY
          team_member_id: '-3oZQKPKVk6gUXU_V5Qa'
          updated_at: '2020-06-11T23:12:04+00:00'
          version: 1
    UpdateWebhookSubscriptionRequest:
      type: object
      description: Updates a [Subscription](entity:WebhookSubscription).
      x-release-status: PUBLIC
      properties:
        subscription:
          $ref: '#/components/schemas/WebhookSubscription'
          description: The [Subscription](entity:WebhookSubscription) to update.
          nullable: true
      example:
        subscription:
          enabled: false
          name: Updated Example Webhook Subscription
    UpdateWebhookSubscriptionResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [UpdateWebhookSubscription](api-endpoint:WebhookSubscriptions-UpdateWebhookSubscription)
        endpoint.


        Note: If there are errors processing the request, the
        [Subscription](entity:WebhookSubscription) is not

        present.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        subscription:
          $ref: '#/components/schemas/WebhookSubscription'
          description: The updated [Subscription](entity:WebhookSubscription).
      example:
        subscription:
          api_version: '2021-12-15'
          created_at: 2022-01-10 23:29:48 +0000 UTC
          enabled: false
          event_types:
            - payment.created
            - payment.updated
          id: wbhk_b35f6b3145074cf9ad513610786c19d5
          name: Updated Example Webhook Subscription
          notification_url: https://example-webhook-url.com
          updated_at: 2022-01-10 23:45:51 +0000 UTC
    UpdateWebhookSubscriptionSignatureKeyRequest:
      type: object
      description: >-
        Updates a [Subscription](entity:WebhookSubscription) by replacing the
        existing signature key with a new one.
      x-release-status: PUBLIC
      properties:
        idempotency_key:
          type: string
          description: >-
            A unique string that identifies the
            [UpdateWebhookSubscriptionSignatureKey](api-endpoint:WebhookSubscriptions-UpdateWebhookSubscriptionSignatureKey)
            request.
          maxLength: 45
          nullable: true
      example:
        idempotency_key: ed80ae6b-0654-473b-bbab-a39aee89a60d
    UpdateWebhookSubscriptionSignatureKeyResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [UpdateWebhookSubscriptionSignatureKey](api-endpoint:WebhookSubscriptions-UpdateWebhookSubscriptionSignatureKey)
        endpoint.


        Note: If there are errors processing the request, the
        [Subscription](entity:WebhookSubscription) is not

        present.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Information on errors encountered during the request.
        signature_key:
          type: string
          description: >-
            The new Square-generated signature key used to validate the origin
            of the webhook event.
          readOnly: true
      example:
        signature_key: 1k9bIJKCeTmSQwyagtNRLg
    UpdateWorkweekConfigRequest:
      type: object
      description: A request to update a `WorkweekConfig` object.
      x-release-status: PUBLIC
      required:
        - workweek_config
      properties:
        workweek_config:
          $ref: '#/components/schemas/WorkweekConfig'
          description: The updated `WorkweekConfig` object.
      example:
        workweek_config:
          start_of_day_local_time: '10:00'
          start_of_week: MON
          version: 10
    UpdateWorkweekConfigResponse:
      type: object
      description: >-
        The response to a request to update a `WorkweekConfig` object. The
        response contains

        the updated `WorkweekConfig` object and might contain a set of `Error`
        objects if

        the request resulted in errors.
      x-release-status: PUBLIC
      properties:
        workweek_config:
          $ref: '#/components/schemas/WorkweekConfig'
          description: The response object.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        workweek_config:
          created_at: '2016-02-04T00:58:24Z'
          id: FY4VCAQN700GM
          start_of_day_local_time: '10:00'
          start_of_week: MON
          updated_at: '2019-02-28T01:04:35Z'
          version: 11
    UpsertBookingCustomAttributeRequest:
      type: object
      description: >-
        Represents an
        [UpsertBookingCustomAttribute](api-endpoint:BookingCustomAttributes-UpsertBookingCustomAttribute)
        request.
      x-release-status: PUBLIC
      required:
        - custom_attribute
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The custom attribute to create or update, with the following fields:


            - `value`. This value must conform to the `schema` specified by the
            definition.

            For more information, see [Value data
            types](https://developer.squareup.com/docs/booking-custom-attributes-api/custom-attributes#value-data-types).


            - `version`. To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control for an update operation, include this optional field and
            specify the current version

            of the custom attribute.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency.
            For more information,

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
          nullable: true
    UpsertBookingCustomAttributeResponse:
      type: object
      description: >-
        Represents an
        [UpsertBookingCustomAttribute](api-endpoint:BookingCustomAttributes-UpsertBookingCustomAttribute)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: PUBLIC
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: The new or updated custom attribute.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute:
          created_at: '2022-11-16T15:50:27Z'
          key: favoriteShampoo
          updated_at: '2022-11-16T15:50:27Z'
          value: Spring Fresh
          version: 1
          visibility: VISIBILITY_READ_ONLY
        errors: []
    UpsertCatalogObjectRequest:
      type: object
      x-release-status: PUBLIC
      required:
        - idempotency_key
        - object
      properties:
        idempotency_key:
          type: string
          description: >-
            A value you specify that uniquely identifies this

            request among all your requests. A common way to create

            a valid idempotency key is to use a Universally unique

            identifier (UUID).


            If you're unsure whether a particular request was successful,

            you can reattempt it with the same idempotency key without

            worrying about creating duplicate objects.


            See
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency)
            for more information.
          minLength: 1
          maxLength: 128
        object:
          $ref: '#/components/schemas/CatalogObject'
          description: >-
            A CatalogObject to be created or updated.


            - For updates, the object must be active (the `is_deleted` field is
            not `true`).

            - For creates, the object ID must start with `#`. The provided ID is
            replaced with a server-generated ID.
      example:
        idempotency_key: af3d1afc-7212-4300-b463-0bfc5314a5ae
        object:
          id: '#Cocoa'
          item_data:
            abbreviation: Ch
            description_html: <p><strong>Hot</strong> Chocolate</p>
            name: Cocoa
            variations:
              - id: '#Small'
                item_variation_data:
                  item_id: '#Cocoa'
                  name: Small
                  pricing_type: VARIABLE_PRICING
                type: ITEM_VARIATION
              - id: '#Large'
                item_variation_data:
                  item_id: '#Cocoa'
                  name: Large
                  price_money:
                    amount: 400
                    currency: USD
                  pricing_type: FIXED_PRICING
                type: ITEM_VARIATION
          type: ITEM
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/UpsertCatalogObject/UpsertCatalogObjectRequest.csharp
        java: >-
          /sdk_samples/Catalog/UpsertCatalogObject/UpsertCatalogObjectRequest.java
        javascript: >-
          /sdk_samples/Catalog/UpsertCatalogObject/UpsertCatalogObjectRequest.javascript
        php: >-
          /sdk_samples/Catalog/UpsertCatalogObject/UpsertCatalogObjectRequest.php
        python: >-
          /sdk_samples/Catalog/UpsertCatalogObject/UpsertCatalogObjectRequest.python
        ruby: >-
          /sdk_samples/Catalog/UpsertCatalogObject/UpsertCatalogObjectRequest.ruby
    UpsertCatalogObjectResponse:
      type: object
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        catalog_object:
          $ref: '#/components/schemas/CatalogObject'
          description: The successfully created or updated CatalogObject.
        id_mappings:
          type: array
          items:
            $ref: '#/components/schemas/CatalogIdMapping'
          description: The mapping between client and server IDs for this upsert.
      example:
        catalog_object:
          id: R2TA2FOBUGCJZNIWJSOSNAI4
          is_deleted: false
          item_data:
            abbreviation: Ch
            description: Hot Chocolate
            description_html: <p><strong>Hot</strong> Chocolate</p>
            description_plaintext: Hot Chocolate
            name: Cocoa
            product_type: REGULAR
            variations:
              - id: QRT53UP4LITLWGOGBZCUWP63
                is_deleted: false
                item_variation_data:
                  item_id: R2TA2FOBUGCJZNIWJSOSNAI4
                  name: Small
                  ordinal: 0
                  pricing_type: VARIABLE_PRICING
                  stockable: true
                present_at_all_locations: true
                type: ITEM_VARIATION
                updated_at: '2021-06-14T15:51:39.021Z'
                version: 1623685899021
              - id: NS77DKEIQ3AEQTCP727DSA7U
                is_deleted: false
                item_variation_data:
                  item_id: R2TA2FOBUGCJZNIWJSOSNAI4
                  name: Large
                  ordinal: 1
                  price_money:
                    amount: 400
                    currency: USD
                  pricing_type: FIXED_PRICING
                  stockable: true
                present_at_all_locations: true
                type: ITEM_VARIATION
                updated_at: '2021-06-14T15:51:39.021Z'
                version: 1623685899021
          present_at_all_locations: true
          type: ITEM
          updated_at: '2021-06-14T15:51:39.021Z'
          version: 1623685899021
        id_mappings:
          - client_object_id: '#Cocoa'
            object_id: R2TA2FOBUGCJZNIWJSOSNAI4
          - client_object_id: '#Small'
            object_id: QRT53UP4LITLWGOGBZCUWP63
          - client_object_id: '#Large'
            object_id: NS77DKEIQ3AEQTCP727DSA7U
      x-sq-sdk-sample-code:
        csharp: >-
          /sdk_samples/Catalog/UpsertCatalogObject/UpsertCatalogObjectResponse.csharp
        java: >-
          /sdk_samples/Catalog/UpsertCatalogObject/UpsertCatalogObjectResponse.java
        javascript: >-
          /sdk_samples/Catalog/UpsertCatalogObject/UpsertCatalogObjectResponse.javascript
        php: >-
          /sdk_samples/Catalog/UpsertCatalogObject/UpsertCatalogObjectResponse.php
        python: >-
          /sdk_samples/Catalog/UpsertCatalogObject/UpsertCatalogObjectResponse.python
        ruby: >-
          /sdk_samples/Catalog/UpsertCatalogObject/UpsertCatalogObjectResponse.ruby
    UpsertCustomerCustomAttributeRequest:
      type: object
      description: >-
        Represents an
        [UpsertCustomerCustomAttribute](api-endpoint:CustomerCustomAttributes-UpsertCustomerCustomAttribute)
        request.
      x-release-status: PUBLIC
      x-params-example: '?customer_id=Z57QXKM2FGXEQDV42W8RBZY7BR&key=favoritemovie'
      required:
        - custom_attribute
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The custom attribute to create or update, with the following fields:


            - `value`. This value must conform to the `schema` specified by the
            definition. 

            For more information, see [Value data
            types](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attributes#value-data-types).


            - `version`. To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control for an update operation, include this optional field and
            specify the current version

            of the custom attribute.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency.
            For more information,

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
          nullable: true
      example:
        custom_attribute:
          value: Dune
    UpsertCustomerCustomAttributeResponse:
      type: object
      description: >-
        Represents an
        [UpsertCustomerCustomAttribute](api-endpoint:CustomerCustomAttributes-UpsertCustomerCustomAttribute)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: PUBLIC
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: The new or updated custom attribute.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute:
          created_at: '2022-04-26T15:50:27Z'
          key: favoritemovie
          updated_at: '2022-04-26T15:50:27Z'
          value: Dune
          version: 1
          visibility: VISIBILITY_READ_ONLY
    UpsertLocationCustomAttributeRequest:
      type: object
      description: >-
        Represents an
        [UpsertLocationCustomAttribute](api-endpoint:LocationCustomAttributes-UpsertLocationCustomAttribute)
        request.
      x-release-status: BETA
      x-params-example: '?location_id=L0TBCBTB7P8RQ&key=bestseller'
      required:
        - custom_attribute
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The custom attribute to create or update, with the following fields:

            - `value`. This value must conform to the `schema` specified by the
            definition.

            For more information, see [Supported data
            types](https://developer.squareup.com/docs/devtools/customattributes/overview#supported-data-types).

            - `version`. To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control for an update operation, include the current version of the
            custom attribute.

            If this is not important for your application, version can be set to
            -1.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency.
            For more information,

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
          nullable: true
      example:
        custom_attribute:
          value: hot cocoa
    UpsertLocationCustomAttributeResponse:
      type: object
      description: >-
        Represents an
        [UpsertLocationCustomAttribute](api-endpoint:LocationCustomAttributes-UpsertLocationCustomAttribute)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: BETA
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: The new or updated custom attribute.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute:
          created_at: '2023-01-09T19:02:58.647Z'
          key: bestseller
          updated_at: '2023-01-09T19:21:04.551Z'
          value: hot cocoa
          version: 2
          visibility: VISIBILITY_READ_WRITE_VALUES
    UpsertMerchantCustomAttributeRequest:
      type: object
      description: >-
        Represents an
        [UpsertMerchantCustomAttribute](api-endpoint:MerchantCustomAttributes-UpsertMerchantCustomAttribute)
        request.
      x-release-status: BETA
      x-params-example: '?merchant_id=DM7VKY8Q63GNP&key=alternative_seller_name'
      required:
        - custom_attribute
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The custom attribute to create or update, with the following fields:

            - `value`. This value must conform to the `schema` specified by the
            definition.

            For more information, see [Supported data
            types](https://developer.squareup.com/docs/devtools/customattributes/overview#supported-data-types).

            - The version field must match the current version of the custom
            attribute definition to enable

            [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            If this is not important for your application, version can be set to
            -1. For any other values, the request fails with a BAD_REQUEST
            error.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency.
            For more information,

            see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          maxLength: 45
          nullable: true
      example:
        custom_attribute:
          value: Ultimate Sneaker Store
    UpsertMerchantCustomAttributeResponse:
      type: object
      description: >-
        Represents an
        [UpsertMerchantCustomAttribute](api-endpoint:MerchantCustomAttributes-UpsertMerchantCustomAttribute)
        response.

        Either `custom_attribute_definition` or `errors` is present in the
        response.
      x-release-status: BETA
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: The new or updated custom attribute.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute:
          created_at: '2023-05-06T19:02:58.647Z'
          key: alternative_seller_name
          updated_at: '2023-05-06T19:21:04.551Z'
          value: Ultimate Sneaker Store
          version: 2
          visibility: VISIBILITY_READ_ONLY
    UpsertOrderCustomAttributeRequest:
      type: object
      description: Represents an upsert request for an order custom attribute.
      x-release-status: BETA
      required:
        - custom_attribute
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: >-
            The custom attribute to create or update, with the following fields:


            - `value`. This value must conform to the `schema` specified by the
            definition. 

            For more information, see [Value data
            types](https://developer.squareup.com/docs/customer-custom-attributes-api/custom-attributes#value-data-types).


            - `version`. To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control, include this optional field and specify the current version
            of the custom attribute.
        idempotency_key:
          type: string
          description: >-
            A unique identifier for this request, used to ensure idempotency. 

            For more information, see
            [Idempotency](https://developer.squareup.com/docs/build-basics/common-api-patterns/idempotency).
          minLength: 1
          maxLength: 45
          nullable: true
      example:
        custom_attribute:
          key: table-number
          value: '42'
          version: 1
    UpsertOrderCustomAttributeResponse:
      type: object
      description: Represents a response from upserting order custom attribute definitions.
      x-release-status: BETA
      properties:
        custom_attribute:
          $ref: '#/components/schemas/CustomAttribute'
          description: The order custom attribute that was created or modified.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example:
        custom_attribute:
          created_at: '2022-10-06T20:41:22.673Z'
          key: table-number
          updated_at: '2022-10-06T20:41:22.673Z'
          value: '42'
          version: 1
          visibility: VISIBILITY_READ_WRITE_VALUES
    UpsertSnippetRequest:
      type: object
      description: Represents an `UpsertSnippet` request.
      x-release-status: PUBLIC
      required:
        - snippet
      properties:
        snippet:
          $ref: '#/components/schemas/Snippet'
          description: The snippet for the site.
      example:
        snippet:
          content: <script>var js = 1;</script>
    UpsertSnippetResponse:
      type: object
      description: >-
        Represents an `UpsertSnippet` response. The response can include either
        `snippet` or `errors`.
      x-release-status: PUBLIC
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
        snippet:
          $ref: '#/components/schemas/Snippet'
          description: The new or updated snippet.
      example:
        snippet:
          content: <script>var js = 1;</script>
          created_at: '2021-03-11T25:40:09.000000Z'
          id: snippet_5d178150-a6c0-11eb-a9f1-437e6a2881e7
          site_id: site_278075276488921835
          updated_at: '2021-03-11T25:40:09.000000Z'
    V1Device:
      type: object
      x-release-status: DEPRECATED
      properties:
        id:
          type: string
          description: The device's Square-issued ID.
        name:
          type: string
          description: The device's merchant-specified name.
          nullable: true
    V1ListOrdersRequest:
      type: object
      x-release-status: DEPRECATED
      x-visibility: SDK_ONLY
      properties:
        order:
          $ref: '#/components/schemas/SortOrder'
          description: |-
            The order in which payments are listed in the response.
            See [SortOrder](#type-sortorder) for possible values
          nullable: true
        limit:
          type: integer
          description: >-
            The maximum number of payments to return in a single response. This
            value cannot exceed 200.
          nullable: true
        batch_token:
          type: string
          description: |-
            A pagination cursor to retrieve the next set of results for your
            original query to the endpoint.
          nullable: true
    V1ListOrdersResponse:
      type: object
      x-release-status: DEPRECATED
      x-visibility: SDK_ONLY
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/V1Order'
    V1Money:
      type: object
      x-release-status: DEPRECATED
      properties:
        amount:
          type: integer
          description: >-
            Amount in the lowest denominated value of this Currency. E.g. in USD

            these are cents, in JPY they are Yen (which do not have a 'cent'
            concept).
          nullable: true
        currency_code:
          $ref: '#/components/schemas/Currency'
          description: |-

            See [Currency](#type-currency) for possible values
          nullable: true
    V1Order:
      type: object
      description: V1Order
      x-release-status: DEPRECATED
      x-visibility: SDK_ONLY
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
          nullable: true
        id:
          type: string
          description: The order's unique identifier.
        buyer_email:
          type: string
          description: The email address of the order's buyer.
          nullable: true
        recipient_name:
          type: string
          description: The name of the order's buyer.
          nullable: true
        recipient_phone_number:
          type: string
          description: The phone number to use for the order's delivery.
          nullable: true
        state:
          $ref: '#/components/schemas/V1OrderState'
          description: |-
            Whether the tax is an ADDITIVE tax or an INCLUSIVE tax.
            See [V1OrderState](#type-v1orderstate) for possible values
          nullable: true
        shipping_address:
          $ref: '#/components/schemas/Address'
          description: The address to ship the order to.
          nullable: true
        subtotal_money:
          $ref: '#/components/schemas/V1Money'
          description: >-
            The amount of all items purchased in the order, before taxes and
            shipping.
          nullable: true
        total_shipping_money:
          $ref: '#/components/schemas/V1Money'
          description: The shipping cost for the order.
          nullable: true
        total_tax_money:
          $ref: '#/components/schemas/V1Money'
          description: The total of all taxes applied to the order.
          nullable: true
        total_price_money:
          $ref: '#/components/schemas/V1Money'
          description: The total cost of the order.
          nullable: true
        total_discount_money:
          $ref: '#/components/schemas/V1Money'
          description: The total of all discounts applied to the order.
          nullable: true
        created_at:
          type: string
          description: The time when the order was created, in ISO 8601 format.
        updated_at:
          type: string
          description: The time when the order was last modified, in ISO 8601 format.
        expires_at:
          type: string
          description: >-
            The time when the order expires if no action is taken, in ISO 8601
            format.
          nullable: true
        payment_id:
          type: string
          description: The unique identifier of the payment associated with the order.
          nullable: true
        buyer_note:
          type: string
          description: A note provided by the buyer when the order was created, if any.
          nullable: true
        completed_note:
          type: string
          description: >-
            A note provided by the merchant when the order's state was set to
            COMPLETED, if any
          nullable: true
        refunded_note:
          type: string
          description: >-
            A note provided by the merchant when the order's state was set to
            REFUNDED, if any.
          nullable: true
        canceled_note:
          type: string
          description: >-
            A note provided by the merchant when the order's state was set to
            CANCELED, if any.
          nullable: true
        tender:
          $ref: '#/components/schemas/V1Tender'
          description: The tender used to pay for the order.
          nullable: true
        order_history:
          type: array
          items:
            $ref: '#/components/schemas/V1OrderHistoryEntry'
          description: The history of actions associated with the order.
          nullable: true
        promo_code:
          type: string
          description: The promo code provided by the buyer, if any.
          nullable: true
        btc_receive_address:
          type: string
          description: >-
            For Bitcoin transactions, the address that the buyer sent Bitcoin
            to.
          nullable: true
        btc_price_satoshi:
          type: number
          description: >-
            For Bitcoin transactions, the price of the buyer's order in satoshi
            (100 million satoshi equals 1 BTC).
          nullable: true
    V1OrderHistoryEntry:
      type: object
      description: V1OrderHistoryEntry
      x-release-status: DEPRECATED
      x-visibility: SDK_ONLY
      properties:
        action:
          $ref: '#/components/schemas/V1OrderHistoryEntryAction'
          description: >-
            The type of action performed on the order.

            See [V1OrderHistoryEntryAction](#type-v1orderhistoryentryaction) for
            possible values
          nullable: true
        created_at:
          type: string
          description: The time when the action was performed, in ISO 8601 format.
    V1OrderHistoryEntryAction:
      type: string
      enum:
        - ORDER_PLACED
        - DECLINED
        - PAYMENT_RECEIVED
        - CANCELED
        - COMPLETED
        - REFUNDED
        - EXPIRED
      x-enum-elements:
        - name: ORDER_PLACED
          description: ''
        - name: DECLINED
          description: ''
        - name: PAYMENT_RECEIVED
          description: ''
        - name: CANCELED
          description: ''
        - name: COMPLETED
          description: ''
        - name: REFUNDED
          description: ''
        - name: EXPIRED
          description: ''
      x-release-status: DEPRECATED
      x-visibility: SDK_ONLY
    V1OrderState:
      type: string
      enum:
        - PENDING
        - OPEN
        - COMPLETED
        - CANCELED
        - REFUNDED
        - REJECTED
      x-enum-elements:
        - name: PENDING
          description: ''
        - name: OPEN
          description: ''
        - name: COMPLETED
          description: ''
        - name: CANCELED
          description: ''
        - name: REFUNDED
          description: ''
        - name: REJECTED
          description: ''
      x-release-status: DEPRECATED
      x-visibility: SDK_ONLY
    V1PhoneNumber:
      type: object
      description: Represents a phone number.
      x-release-status: DEPRECATED
      required:
        - calling_code
        - number
      properties:
        calling_code:
          type: string
          description: >-
            The phone number's international calling code. For US phone numbers,
            this value is +1.
        number:
          type: string
          description: The phone number.
    V1RetrieveOrderRequest:
      type: object
      x-release-status: DEPRECATED
      x-visibility: SDK_ONLY
      properties: {}
    V1Tender:
      type: object
      description: >-
        A tender represents a discrete monetary exchange. Square represents this

        exchange as a money object with a specific currency and amount, where
        the

        amount is given in the smallest denomination of the given currency.


        Square POS can accept more than one form of tender for a single payment
        (such

        as by splitting a bill between a credit card and a gift card). The
        `tender`

        field of the Payment object lists all forms of tender used for the
        payment.


        Split tender payments behave slightly differently from single tender
        payments:


        The receipt_url for a split tender corresponds only to the first tender
        listed

        in the tender field. To get the receipt URLs for the remaining tenders,
        use

        the receipt_url fields of the corresponding Tender objects.


        *A note on gift cards**: when a customer purchases a Square gift card
        from a

        merchant, the merchant receives the full amount of the gift card in the

        associated payment.


        When that gift card is used as a tender, the balance of the gift card is

        reduced and the merchant receives no funds. A `Tender` object with a
        type of

        `SQUARE_GIFT_CARD` indicates a gift card was used for some or all of the

        associated payment.
      x-release-status: DEPRECATED
      properties:
        id:
          type: string
          description: The tender's unique ID.
        type:
          $ref: '#/components/schemas/V1TenderType'
          description: |-
            The type of tender.
            See [V1TenderType](#type-v1tendertype) for possible values
          nullable: true
        name:
          type: string
          description: A human-readable description of the tender.
          nullable: true
        employee_id:
          type: string
          description: The ID of the employee that processed the tender.
          nullable: true
        receipt_url:
          type: string
          description: The URL of the receipt for the tender.
          nullable: true
        card_brand:
          $ref: '#/components/schemas/V1TenderCardBrand'
          description: |-
            The brand of credit card provided.
            See [V1TenderCardBrand](#type-v1tendercardbrand) for possible values
          nullable: true
        pan_suffix:
          type: string
          description: The last four digits of the provided credit card's account number.
          nullable: true
        entry_method:
          $ref: '#/components/schemas/V1TenderEntryMethod'
          description: >-
            The tender's unique ID.

            See [V1TenderEntryMethod](#type-v1tenderentrymethod) for possible
            values
          nullable: true
        payment_note:
          type: string
          description: >-
            Notes entered by the merchant about the tender at the time of
            payment, if any. Typically only present for tender with the type:
            OTHER.
          nullable: true
        total_money:
          $ref: '#/components/schemas/V1Money'
          description: The total amount of money provided in this form of tender.
          nullable: true
        tendered_money:
          $ref: '#/components/schemas/V1Money'
          description: The amount of total_money applied to the payment.
          nullable: true
        tendered_at:
          type: string
          description: The time when the tender was created, in ISO 8601 format.
          nullable: true
        settled_at:
          type: string
          description: The time when the tender was settled, in ISO 8601 format.
          nullable: true
        change_back_money:
          $ref: '#/components/schemas/V1Money'
          description: The amount of total_money returned to the buyer as change.
          nullable: true
        refunded_money:
          $ref: '#/components/schemas/V1Money'
          description: >-
            The total of all refunds applied to this tender. This amount is
            always negative or zero.
          nullable: true
        is_exchange:
          type: boolean
          description: >-
            Indicates whether or not the tender is associated with an exchange.
            If is_exchange is true, the tender represents the value of goods
            returned in an exchange not the actual money paid. The exchange
            value reduces the tender amounts needed to pay for items purchased
            in the exchange.
          nullable: true
    V1TenderCardBrand:
      type: string
      enum:
        - OTHER_BRAND
        - VISA
        - MASTER_CARD
        - AMERICAN_EXPRESS
        - DISCOVER
        - DISCOVER_DINERS
        - JCB
        - CHINA_UNIONPAY
        - SQUARE_GIFT_CARD
      x-enum-elements:
        - name: OTHER_BRAND
          description: ''
        - name: VISA
          description: ''
        - name: MASTER_CARD
          description: ''
        - name: AMERICAN_EXPRESS
          description: ''
        - name: DISCOVER
          description: ''
        - name: DISCOVER_DINERS
          description: ''
        - name: JCB
          description: ''
        - name: CHINA_UNIONPAY
          description: ''
        - name: SQUARE_GIFT_CARD
          description: ''
      description: The brand of a credit card.
      x-release-status: DEPRECATED
    V1TenderEntryMethod:
      type: string
      enum:
        - MANUAL
        - SCANNED
        - SQUARE_CASH
        - SQUARE_WALLET
        - SWIPED
        - WEB_FORM
        - OTHER
      x-enum-elements:
        - name: MANUAL
          description: ''
        - name: SCANNED
          description: ''
        - name: SQUARE_CASH
          description: ''
        - name: SQUARE_WALLET
          description: ''
        - name: SWIPED
          description: ''
        - name: WEB_FORM
          description: ''
        - name: OTHER
          description: ''
      x-release-status: DEPRECATED
    V1TenderType:
      type: string
      enum:
        - CREDIT_CARD
        - CASH
        - THIRD_PARTY_CARD
        - NO_SALE
        - SQUARE_WALLET
        - SQUARE_GIFT_CARD
        - UNKNOWN
        - OTHER
      x-enum-elements:
        - name: CREDIT_CARD
          description: ''
        - name: CASH
          description: ''
        - name: THIRD_PARTY_CARD
          description: ''
        - name: NO_SALE
          description: ''
        - name: SQUARE_WALLET
          description: ''
        - name: SQUARE_GIFT_CARD
          description: ''
        - name: UNKNOWN
          description: ''
        - name: OTHER
          description: ''
      x-release-status: DEPRECATED
    V1UpdateOrderRequest:
      type: object
      description: V1UpdateOrderRequest
      x-release-status: DEPRECATED
      x-visibility: SDK_ONLY
      required:
        - action
      properties:
        action:
          $ref: '#/components/schemas/V1UpdateOrderRequestAction'
          description: >-
            The action to perform on the order (COMPLETE, CANCEL, or REFUND).

            See [V1UpdateOrderRequestAction](#type-v1updateorderrequestaction)
            for possible values
        shipped_tracking_number:
          type: string
          description: >-
            The tracking number of the shipment associated with the order. Only
            valid if action is COMPLETE.
          nullable: true
        completed_note:
          type: string
          description: >-
            A merchant-specified note about the completion of the order. Only
            valid if action is COMPLETE.
          nullable: true
        refunded_note:
          type: string
          description: >-
            A merchant-specified note about the refunding of the order. Only
            valid if action is REFUND.
          nullable: true
        canceled_note:
          type: string
          description: >-
            A merchant-specified note about the canceling of the order. Only
            valid if action is CANCEL.
          nullable: true
    V1UpdateOrderRequestAction:
      type: string
      enum:
        - COMPLETE
        - CANCEL
        - REFUND
      x-enum-elements:
        - name: COMPLETE
          description: ''
        - name: CANCEL
          description: ''
        - name: REFUND
          description: ''
      x-release-status: DEPRECATED
      x-visibility: SDK_ONLY
    Vendor:
      type: object
      description: Represents a supplier to a seller.
      x-release-status: BETA
      properties:
        id:
          type: string
          description: >-
            A unique Square-generated ID for the [Vendor](entity:Vendor).

            This field is required when attempting to update a
            [Vendor](entity:Vendor).
          maxLength: 100
        created_at:
          type: string
          description: |-
            An RFC 3339-formatted timestamp that indicates when the
            [Vendor](entity:Vendor) was created.
          maxLength: 34
          readOnly: true
        updated_at:
          type: string
          description: |-
            An RFC 3339-formatted timestamp that indicates when the
            [Vendor](entity:Vendor) was last updated.
          maxLength: 34
          readOnly: true
        name:
          type: string
          description: >-
            The name of the [Vendor](entity:Vendor).

            This field is required when attempting to create or update a
            [Vendor](entity:Vendor).
          maxLength: 100
          nullable: true
        address:
          $ref: '#/components/schemas/Address'
          description: The address of the [Vendor](entity:Vendor).
          nullable: true
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/VendorContact'
          description: The contacts of the [Vendor](entity:Vendor).
          nullable: true
        account_number:
          type: string
          description: The account number of the [Vendor](entity:Vendor).
          maxLength: 100
          nullable: true
        note:
          type: string
          description: A note detailing information about the [Vendor](entity:Vendor).
          maxLength: 4096
          nullable: true
        version:
          type: integer
          description: The version of the [Vendor](entity:Vendor).
        status:
          $ref: '#/components/schemas/VendorStatus'
          description: |-
            The status of the [Vendor](entity:Vendor).
            See [Status](#type-status) for possible values
          nullable: true
    VendorContact:
      type: object
      description: Represents a contact of a [Vendor](entity:Vendor).
      x-release-status: BETA
      required:
        - ordinal
      properties:
        id:
          type: string
          description: >-
            A unique Square-generated ID for the
            [VendorContact](entity:VendorContact).

            This field is required when attempting to update a
            [VendorContact](entity:VendorContact).
          maxLength: 100
        name:
          type: string
          description: >-
            The name of the [VendorContact](entity:VendorContact).

            This field is required when attempting to create a
            [Vendor](entity:Vendor).
          maxLength: 255
          nullable: true
        email_address:
          type: string
          description: The email address of the [VendorContact](entity:VendorContact).
          maxLength: 255
          nullable: true
        phone_number:
          type: string
          description: The phone number of the [VendorContact](entity:VendorContact).
          maxLength: 255
          nullable: true
        removed:
          type: boolean
          description: The state of the [VendorContact](entity:VendorContact).
          nullable: true
        ordinal:
          type: integer
          description: The ordinal of the [VendorContact](entity:VendorContact).
    VendorStatus:
      type: string
      enum:
        - ACTIVE
        - INACTIVE
      x-enum-elements:
        - name: ACTIVE
          description: Vendor is active and can receive purchase orders.
        - name: INACTIVE
          description: Vendor is inactive and cannot receive purchase orders.
      description: |-
        The status of the [Vendor](entity:Vendor),
        whether a [Vendor](entity:Vendor) is active or inactive.
      x-release-status: BETA
    VisibilityFilter:
      type: string
      enum:
        - ALL
        - READ
        - READ_WRITE
      x-enum-elements:
        - name: ALL
          description: All custom attributes or custom attribute definitions.
        - name: READ
          description: >-
            All custom attributes or custom attribute definitions with the
            `visibility` field set to `VISIBILITY_READ_ONLY` or
            `VISIBILITY_READ_WRITE_VALUES`.
        - name: READ_WRITE
          description: >-
            All custom attributes or custom attribute definitions with the
            `visibility` field set to `VISIBILITY_READ_WRITE_VALUES`.
      description: >-
        Enumeration of visibility-filter values used to set the ability to view
        custom attributes or custom attribute definitions.
      x-release-status: PUBLIC
    VoidTransactionRequest:
      type: object
      x-release-status: DEPRECATED
      properties: {}
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/VoidTransaction/VoidTransactionRequest.csharp
        java: /sdk_samples/VoidTransaction/VoidTransactionRequest.java
        javascript: /sdk_samples/VoidTransaction/VoidTransactionRequest.javascript
        php: /sdk_samples/VoidTransaction/VoidTransactionRequest.php
        python: /sdk_samples/VoidTransaction/VoidTransactionRequest.python
        ruby: /sdk_samples/VoidTransaction/VoidTransactionRequest.ruby
    VoidTransactionResponse:
      type: object
      description: >-
        Defines the fields that are included in the response body of

        a request to the
        [VoidTransaction](api-endpoint:Transactions-VoidTransaction) endpoint.
      x-release-status: DEPRECATED
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          description: Any errors that occurred during the request.
      example: {}
      x-sq-sdk-sample-code:
        csharp: /sdk_samples/VoidTransaction/VoidTransactionResponse.csharp
        java: /sdk_samples/VoidTransaction/VoidTransactionResponse.java
        javascript: /sdk_samples/VoidTransaction/VoidTransactionResponse.javascript
        php: /sdk_samples/VoidTransaction/VoidTransactionResponse.php
        python: /sdk_samples/VoidTransaction/VoidTransactionResponse.python
        ruby: /sdk_samples/VoidTransaction/VoidTransactionResponse.ruby
    WageSetting:
      type: object
      description: >-
        Represents information about the overtime exemption status, job
        assignments, and compensation

        for a [team member](entity:TeamMember).
      x-release-status: PUBLIC
      properties:
        team_member_id:
          type: string
          description: The ID of the team member associated with the wage setting.
          nullable: true
        job_assignments:
          type: array
          items:
            $ref: '#/components/schemas/JobAssignment'
          description: >-
            **Required** The ordered list of jobs that the team member is
            assigned to.

            The first job assignment is considered the team member's primary
            job.
          nullable: true
        is_overtime_exempt:
          type: boolean
          description: >-
            Whether the team member is exempt from the overtime rules of the
            seller's country.
          nullable: true
        version:
          type: integer
          description: >-
            **Read only** Used for resolving concurrency issues. The request
            fails if the version

            provided does not match the server version at the time of the
            request. If not provided,

            Square executes a blind write, potentially overwriting data from
            another write. For more information,

            see [optimistic
            concurrency](https://developer.squareup.com/docs/working-with-apis/optimistic-concurrency).
        created_at:
          type: string
          description: The timestamp when the wage setting was created, in RFC 3339 format.
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp when the wage setting was last updated, in RFC 3339
            format.
          readOnly: true
    WebhookSubscription:
      type: object
      description: >-
        Represents the details of a webhook subscription, including notification
        URL,

        event types, and signature key.
      x-release-status: PUBLIC
      properties:
        id:
          type: string
          description: A Square-generated unique ID for the subscription.
          maxLength: 64
          readOnly: true
        name:
          type: string
          description: The name of this subscription.
          maxLength: 64
          nullable: true
        enabled:
          type: boolean
          description: >-
            Indicates whether the subscription is enabled (`true`) or not
            (`false`).
          nullable: true
        event_types:
          type: array
          items:
            type: string
          description: The event types associated with this subscription.
          nullable: true
        notification_url:
          type: string
          description: The URL to which webhooks are sent.
          nullable: true
        api_version:
          type: string
          description: |-
            The API version of the subscription.
            This field is optional for `CreateWebhookSubscription`. 
            The value defaults to the API version used by the application.
          nullable: true
        signature_key:
          type: string
          description: >-
            The Square-generated signature key used to validate the origin of
            the webhook event.
          readOnly: true
        created_at:
          type: string
          description: >-
            The timestamp of when the subscription was created, in RFC 3339
            format. For example, "2016-09-04T23:59:33.123Z".
          readOnly: true
        updated_at:
          type: string
          description: >-
            The timestamp of when the subscription was last updated, in RFC 3339
            format.

            For example, "2016-09-04T23:59:33.123Z".
          readOnly: true
    Weekday:
      type: string
      enum:
        - MON
        - TUE
        - WED
        - THU
        - FRI
        - SAT
        - SUN
      x-enum-elements:
        - name: MON
          description: Monday
        - name: TUE
          description: Tuesday
        - name: WED
          description: Wednesday
        - name: THU
          description: Thursday
        - name: FRI
          description: Friday
        - name: SAT
          description: Saturday
        - name: SUN
          description: Sunday
      description: The days of the week.
      x-release-status: PUBLIC
    WorkweekConfig:
      type: object
      description: |-
        Sets the day of the week and hour of the day that a business starts a
        workweek. This is used to calculate overtime pay.
      x-release-status: PUBLIC
      required:
        - start_of_week
        - start_of_day_local_time
      properties:
        id:
          type: string
          description: The UUID for this object.
        start_of_week:
          $ref: '#/components/schemas/Weekday'
          description: |-
            The day of the week on which a business week starts for
            compensation purposes.
            See [Weekday](#type-weekday) for possible values
        start_of_day_local_time:
          type: string
          description: >-
            The local time at which a business week starts. Represented as a

            string in `HH:MM` format (`HH:MM:SS` is also accepted, but seconds
            are

            truncated).
          minLength: 1
        version:
          type: integer
          description: >-
            Used for resolving concurrency issues. The request fails if the
            version

            provided does not match the server version at the time of the
            request. If not provided,

            Square executes a blind write; potentially overwriting data from
            another

            write.
        created_at:
          type: string
          description: A read-only timestamp in RFC 3339 format; presented in UTC.
          readOnly: true
        updated_at:
          type: string
          description: A read-only timestamp in RFC 3339 format; presented in UTC.
          readOnly: true
  x-apis:
    ApplePay:
      name: Apple Pay
      summary: Apple Pay support APIs
      description: >-

        The Apple Pay APIs provides an easy way for platform developers

        to bulk activate Web Apple Pay with Square for merchants using their
        platform.


        For more information, see the following guides:

        - [Web Payments
        SDK](https://developer.squareup.com/docs/web-payments/apple-pay)

        - [In-App Payments
        SDK](https://developer.squareup.com/docs/in-app-payments-sdk/add-digital-wallets/apple-pay)
    BankAccounts:
      name: Bank Accounts
      summary: Get a list of a seller's bank accounts.
      description: >

        The Bank Accounts API allows you to get basic details about a seller's
        bank account, such as the

        last few digits of the account number and the routing number. It can be
        paired with the Payouts API to understand the

        pattern of deposits and withdrawals from a seller's bank account.


        For more information, see the following guides:
         - [Bank Accounts](https://developer.squareup.com/docs/bank-accounts-api)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    BookingCustomAttributes:
      name: Booking Custom Attributes
      summary: >-
        Create and manage booking-related custom attribute definitions and
        custom attributes.
      description: >

        Use the Booking Custom Attributes API to create and manage custom
        attributes for bookings to store properties or 

        metadata to support seller-specific customizations of and extensions to
        the `Booking` object. 


        For more information, see the following guides: 
         - [Booking Custom Attributes](https://developer.squareup.com/docs/booking-custom-attributes-api/overview).
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Bookings:
      name: Bookings
      summary: Create and manage bookings for Square sellers.
      description: >

        The Bookings API allows you to create, retrieve, update, and cancel
        appointments online. When used with other Square APIs (such as the
        Locations API, Team API, Catalog API, and Customers API), the Bookings
        API lets you create online-booking applications for users to book
        services provided by Square sellers.   


        For more information, see the following guides:
         - [Bookings](https://developer.squareup.com/docs/bookings-api/what-it-is)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Cards:
      name: Cards
      summary: Use the Cards API to save a credit or debit card on file.
      description: >-

        You can use the [CreateCard](/reference/square/cards-api/create-card)
        endpoint to save a credit or debit card to a Square account.

        Developers can integrate the Cards API in their application to let
        Square sellers:


        - **Save a card that can be charged by any Square seller who uses your
        application.** Your application specifies the organization access token
        in the `CreateCard` request.

        - **Save a card that can be charged by a single Square seller.**  Your
        application specifies the access token of the specific seller account in
        the `CreateCard` request.


        The Cards API also supports other endpoints to manage the cards.


        For more information, see the following guides:
         - [Cards](https://developer.squareup.com/docs/cards-api/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    CashDrawers:
      name: Cash Drawers
      summary: Get details about cash drawer shifts.
      description: >-

        Cash drawer shifts track cash transactions so that the total money in
        the cash drawers can be reconciled for a

        specific period of time (a cash drawer shift), for a particular device,
        in a particular location. The Cash Drawer Shifts API

        enables you to list and retrieve information about cash drawer shifts.


        For more information, see the following guide:
         - [Cash Drawer Shifts](https://developer.squareup.com/docs/cashdrawershift-api/reporting)
    Catalog:
      name: Catalog
      summary: >-
        Programmatically catalogs a Square sellers products for sale and
        services for hire.
      description: >-

        The Catalog API allows you to programmatically catalog products or
        services, including items, variations, categories, discounts, taxes,
        modifiers, and more.


        For more information, see the following guides:
         - [Catalog](https://developer.squareup.com/docs/catalog-api/what-it-does)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Checkout:
      name: Checkout
      summary: >-
        Accept payments through a pre-built, Square-hosted checkout page. No
        frontend required.
      description: >-

        With the Square Checkout API, your customers can pay for a purchase
        through a simple, Square-hosted checkout page. It can be integrated into
        any payments workflow with minimal coding. 


        You can create and configure your checkout page through a
        `CreatePaymentLink` request, specifying the accepted payment methods and
        checkout options like tipping and custom fields.  You can also configure
        a URL for customers to be redirected to once they complete their
        purchase. 


        First time Square developers should utilize the payment link endpoints
        to create, update, retrieve, and list checkout pages. 


        For more information, see the following guide:
         - [Checkout](https://developer.squareup.com/docs/checkout-api-overview)
    CustomerCustomAttributes:
      name: Customer Custom Attributes
      summary: >-
        Create and manage customer-related custom attribute definitions and
        custom attributes.
      description: >-

        Use the Customer Custom Attributes API to create and manage custom
        attributes for customer profiles. Custom attributes can be used to store
        properties or metadata that simplify integration, synchronization, and
        personalization workflows. After a custom attribute definition is
        created in a Square seller account, the custom attribute value can be
        set for customer profiles in the seller's Customer Directory.


        For more information, see the following guides:
         - [Customer Custom Attributes](https://developer.squareup.com/docs/customer-custom-attributes-api/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    CustomerGroups:
      name: Customer Groups
      summary: >-
        Create and manage customer groups to streamline and automate workflows
        and help personalize customer interactions.
      description: >-

        The Customer Groups API lets you create and manage customer groups to
        provide targeted promotions or take other customized actions based on
        group membership. For example, you can create Weekly, Monthly, and
        Quarterly customer groups and add customers to them based on their
        preferences to receive marketing promotions on a weekly, monthly, and
        quarterly basis. You can then use the information to manage your
        marketing email schedule. 


        You can use the Customer Groups API to retrieve and manage customer
        groups. You can use the Customers API to add customers to and remove
        customers from groups and search for customers based on group
        membership.


        For more information, see the following guide:
         - [Customer Groups](https://developer.squareup.com/docs/customer-groups-api/what-it-does)
    CustomerSegments:
      name: Customer Segments
      summary: >-
        Retrieve customer segments (also called smart groups) in a business
        account.
      description: >-

        The Customer Segments API lets you retrieve information about the
        segments defined for a business. Square sellers can create customer
        segments in the Seller Dashboard or Point of Sale by defining filters
        for the segment. For example, a segment can include customers who have
        visited more than 10 times. Customers are automatically added to and
        removed from the segment over time based on this criterion. 


        You can inspect the customer's `segment_ids` property to determine which
        segments a customer belongs to. Then, you can use the Customer Segments
        API to retrieve basic details about each segment, such as the segment
        name and the time when it was created.


        For more information, see the following guide:
         - [Customer Segments](https://developer.squareup.com/docs/customer-segments-api/what-it-does)
    Customers:
      name: Customers
      summary: Create and manage customer profiles and sync CRM systems with Square.
      description: >-

        The Customers API enables you to create and manage customer profiles, as
        well as search for customers based on various criteria (including
        customer group membership). You can also use the API to sync contacts
        between your CRM system and Square.


        For more information, see the following guides:
         - [Customers](https://developer.squareup.com/docs/customers-api/what-it-does)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Devices:
      name: Devices
      summary: >-
        Create device codes used to connect Square Terminal with a 3rd-party
        point of sale system, and get details about all connected Terminals. 
      description: |-

        For more information, see the following guides:
         - [Devices](https://developer.squareup.com/docs/terminal-api/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Disputes:
      name: Disputes
      summary: Use the Disputes API to manage disputes (chargebacks).
      description: >-

        A seller has the following options to process a dispute:


        - Accept the dispute using the
        [AcceptDispute](/reference/square/disputes-api/accept-dispute) endpoint.
        Square returns the disputed amount from the account balance of the
        Square account.

        - Challenge the dispute using the
        [SubmitEvidence](/reference/square/disputes-api/submit-evidence)
        endpoint. If the payment was valid, you can contest the disputed
        payment.

        You submit supporting evidence you have about the transaction, such as
        receipts, invoices, email correspondence, proof of delivery, or photos.

        You upload evidence using the
        [CreateDisputeEvidenceFile](/reference/square/disputes-api/create-dispute-evidence-file)
        endpoint.


        The Disputes API also supports other endpoints useful in dispute
        management.


        For more information, see the following guides:
         - [Disputes](https://developer.squareup.com/docs/disputes-api/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Employees:
      name: Employees
      summary: >-
        Pull employee data into accounting and payroll systems with the
        Employees API.
      description: >-

        The Employees API allows applications to retrieve a roster of employees
        registered in the Square Point

        of Sale system, which can be useful in payroll and account contexts.


        Prior to 2020-08-26, the Employees API was best used in conjunction with
        the Labor API, where you provide employee IDs to

        manage shifts, breaks, and wages. After that deprecation date, the Team
        API should be used.


        For information about migrating your code to the Team API, see [Migrate
        from the Square Employees
        API](https://developer.squareup.com/docs/team/migrate-from-v2-employees?environment=master&preview=true)
    Events:
      name: Events
      summary: Search for Square API events that occur within a 28-day timeframe.
      description: >

        If you don't need a real-time response to data changes or need a
        disaster recovery or reconciliation mechanism for missed webhook events
        (caused by server outages, misconfigured webhook subscriptions, network
        errors, and other events), you can use the Events API instead of webhook
        subscriptions managed manually or through the Webhook Subscriptions API.


        Because Square events are owned by the application and not any one
        seller, you cannot use OAuth access tokens with the Events API. You must
        use the applications [personal access
        token](/docs/build-basics/access-tokens).


        For more information, see:
         - [Events API](https://developer.squareup.com/docs/events-api/overview) 
    GiftCardActivities:
      name: Gift Card Activities
      summary: Create and retrieve gift card activities.
      description: >-

        Use the Gift Card Activities API to create activities for a Square gift
        card (such as activating or reloading the gift card) and to track gift
        card activities. The Gift Card Activities API is used with the [Gift
        Cards
        API](https://developer.squareup.com/reference/square/gift-cards-api) to
        manage the gift card program for a Square seller.


        For more information, see the following guides:
         - [Gift Card Activities](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    GiftCards:
      name: Gift Cards
      summary: Create and retrieve gift cards and manage gift cards on file.
      description: >-

        [Square Gift Cards](https://squareup.com/gift-cards) enable sellers to
        boost sales and attract new customers. Customers can purchase gift cards
        and redeem them at any of the seller's locations. Sellers can manage
        gift cards and track activity.


        Use the Gift Cards API to create and retrieve gift cards (for example,
        to get the gift card balance) and manage gift cards on file by linking
        or unlinking gift cards with customers. After creating a gift card, use
        the [Gift Card Activities
        API](https://developer.squareup.com/reference/square/gift-card-activities-api)
        to activate the gift card with an initial balance and manage other
        activities.


        For more information, see the following guides:
         - [Gift Cards](https://developer.squareup.com/docs/gift-cards/using-gift-cards-api)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Inventory:
      name: Inventory
      summary: Programmatically manages a Square sellers inventory of catalog items.
      description: >-

        The Inventory API allows you to programmatically manage inventory counts
        and inventory changes of products or services.


        For more information, see the following guides:
         - [Inventory](https://developer.squareup.com/docs/inventory-api/what-it-does)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Invoices:
      name: Invoices
      summary: >-
        Create, configure, and publish invoices for orders that were created
        using the Orders API.
      description: >-

        [Square Invoices](https://squareup.com/invoices) makes it easy for
        sellers to request and collect payments from their customers. Square
        notifies customers and processes invoice payments.


        Use the Invoices API to create and manage invoices for orders that were
        created using the Orders API. After you create the invoice and configure
        its delivery method, payment schedule, and other invoice settings, you
        can publish the invoice. Depending on the invoice settings, Square can
        send the invoice to the customer or automatically charge a card on file.
        Square hosts each invoice on a web page where customers can pay for it.


        For more information, see the following guides:
         - [Invoices](https://developer.squareup.com/docs/invoices-api/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Labor:
      name: Labor
      summary: Manage shifts, breaks, and wages for employees in Square Point of Sale.
      description: >-

        The Labor API allows you to see when employees clocked in and out, how
        much they worked during different

        periods, and how many breaks they took. You can also call the API to
        register a past break, adjust a shift,

        or update a wage.


        This API is used in conjunction with the Team API.


        For more information, see the following guides:
         - [Labor](https://developer.squareup.com/docs/labor-api/what-it-does)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    LocationCustomAttributes:
      name: Location Custom Attributes
      summary: >-
        Create and manage location-related custom attribute definitions and
        custom attributes.
      description: >-

        Use the Location Custom Attributes API to create and manage custom
        attributes for locations. Custom attributes can be used to store
        properties or metadata that simplify integration, synchronization, and
        personalization workflows. After a custom attribute definition is
        created in a Square seller account, the custom attribute value can be
        set for locations.


        For more information, see the following guides:
         - [Location Custom Attributes](https://developer.squareup.com/docs/location-custom-attributes-api/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Locations:
      name: Locations
      summary: Create and manage the locations of a seller's business.
      description: >-

        Many sellers use multiple locations to track where they make sales. The
        Locations API allows you to

        create and manage data about those locations, such as their addresses,
        names, and business hours.


        For more information, see the following guides:
         - [Locations](https://developer.squareup.com/docs/locations-api)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Loyalty:
      name: Loyalty
      summary: >-
        Enroll buyers in a Square loyalty program, view program settings, manage
        and track loyalty activity, and create and manage promotions.
      description: >-

        Sellers subscribe to [Square
        Loyalty](https://squareup.com/software/loyalty) to offer a loyalty
        program that can increase repeat visits to their business by rewarding
        customers.


        Use the Loyalty API to create loyalty accounts for buyers and enable
        them to earn points for purchases and redeem points for reward
        discounts. Also use the Loyalty API to retrieve details about the
        loyalty program, create and manage loyalty promotions that extend the
        base program, and track balance-changing events for loyalty accounts.


        For more information, see the following guides:
         - [Loyalty](https://developer.squareup.com/docs/loyalty-api/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    MerchantCustomAttributes:
      name: Merchant Custom Attributes
      summary: >-
        Create and manage merchant-related custom attribute definitions and
        custom attributes.
      description: >-

        Use the Merchant Custom Attributes API to create and manage custom
        attributes for merchants that connect to your application. Custom
        attributes can be used to store properties or metadata that simplify
        integration, synchronization, and personalization workflows.


        For more information, see the following guides:
         - [Merchant Custom Attributes](https://developer.squareup.com/docs/merchant-custom-attributes-api/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Merchants:
      name: Merchants
      summary: Retrieve information about an organization that sells with Square.
      description: >-

        The Merchants API groups individual seller locations into larger
        organizations, allowing them to operate as a single entity. Each
        merchant represents one organization or business that sells with Square.
        Use this API to retrieve core information about the organization
        connecting to your application such as the merchant ID, language
        preferences, country, account status, and the name of the overall
        business.


        For more information, see the following guide:
         - [Merchants](https://developer.squareup.com/docs/merchants-api)
    MobileAuthorization:
      name: Mobile Authorization
      summary: Authorize Reader SDK applications to take in-person payments.
      description: >-

        The Mobile Authorization API accepts an account credential (an OAuth
        token or a personal access token) and a

        location ID and returns an authorization code that custom mobile
        applications can use to initialize Square mobile

        solutions, like Reader SDK, to accept payments using Square hardware.


        For more information, see the following guide:
         - [Mobile Authorization](https://developer.squareup.com/docs/mobile-authz/what-it-does)
    OAuth:
      name: OAuth
      summary: >-
        Allow your application to gain programmatic access to other seller
        accounts.
      description: >-

        The Square OAuth API lets applications request and obtain permission
        from a Square account to make API

        calls on behalf of that account. Applications can request individual
        permissions so that users do not need

        to grant full access to their Square accounts.


        For more information, see the following guides:
         - [OAuth](https://developer.squareup.com/docs/oauth-api/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    OrderCustomAttributes:
      name: Order Custom Attributes
      summary: >-
        Create and manage order-related custom attribute definitions and custom
        attributes.
      description: >-

        Use the Order Custom Attributes API to create and manage custom
        attributes for orders. Custom attributes can be used to store properties
        or metadata that simplify integration, synchronization, and
        personalization workflows. After a custom attribute definition is
        created in a Square seller account, the custom attribute value can be
        set for orders.


        For more information, see the following guides:
         - [Order Custom Attributes](https://developer.squareup.com/docs/orders-custom-attributes-api/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Orders:
      name: Orders
      summary: >-
        Get sales data for a Square seller, itemize payments, push orders to
        POS, and more.
      description: >-

        The Orders API is your one-stop shop for adding rich functionality to
        payments. You can itemize

        payments using custom line items or catalog objects, send orders to
        physical Point of Sale devices

        to be fulfilled, attach a customer to a payment, and more.


        In addition, the Orders API lets you search through all of a seller's
        past sales and returns itemization

        data, customer references, and other details from sales made using POS
        or online.


        If you use the Square Orders API with a non-Square payments provider,
        Square charges a transaction fee. For more information, see [Orders API
        fee
        structure.](https://developer.squareup.com/docs/payments-pricing#orders-api-fee-structure)


        For more information, see the following guides:
         - [Orders](https://developer.squareup.com/docs/orders-api/what-it-does)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Payments:
      name: Payments
      summary: The Payments API lets developers take and manage payments.
      description: >-

        Applications need the following input to take a payment:


        - The amount to charge.

        - The payment recipient. The payment goes to the account identified by
        the Authorization header in the API request.

        - The payment source. The source can be a payment token or card on file.

          You can generate a payment token using the Web Payments SDK and the In-App Payments SDK. For working code examples, see [Square Connect API Examples](https://github.com/square/connect-api-examples).

          A card on file is a credit card, debit card, or gift card that is associated with a customer. 
          You can create a customer and add a card on file using Square APIs, the Square Seller Dashboard, or the Square Point of Sale application.

          For more information, see the following guides:
         - [Payments](https://developer.squareup.com/docs/payments-api/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Payouts:
      name: Payouts
      summary: Get a list of deposits and withdrawals from a seller's bank accounts.
      description: >-

        The Payouts API allows you to see a complete list of payouts made to a
        seller's banking destination,

        with a list of payout entries that describe the payments associated with
        each payout. It can be paired with the

        Bank Accounts API to add detail about which bank account each payout was
        made to.


        For more information, see the following guide:
         - [Payouts](https://developer.squareup.com/docs/payouts/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Refunds:
      name: Refunds
      summary: Manage and issue refunds for payments made to Square sellers.
      description: >-

        The following applies to refunds:


        - You cannot refund more than what was originally collected.

        - The refund amount must be available in the account's Square balance.
        If the amount is not available, Square attempts to take money out of
          the associated bank account. Refunds are in a state of PENDING until the funds are secured.
        - If funds cannot be secured, the refund is not completed and the buyer
        does not receive a credit. The refund has 
          a status of FAILED. Future refunds to this payment are not allowed and the buyer should be reimbursed by other means.
        - You can refund only payments with status COMPLETED. You cannot refund
        an APPROVED payment; however, you can cancel
          an approved payment.

        For more information, see the following guides:
         - [Refunds](https://developer.squareup.com/docs/payments-api/refund-payments)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Reporting:
      name: Reporting
      summary: Deprecated - Use the Orders and Payments APIs instead.
      description: >-

        Prior to 2019/08/15, the Reporting API was the way to review multi-party
        payments taken with the Transactions

        API. The Payments API now includes an "application fee" parameter you
        can use to replace this functionality.
    Settlements:
      name: Settlements
      summary: Get a list of deposits and withdrawals from a seller's bank accounts.
      description: >-

        __The V1 Settlements API has been deprecated__. The Settlements API
        allows you to see a complete list of settlements made to a seller's bank
        account,

        with a list of settlement entries that describe the payments associated
        with each settlement. It can be paired with the

        Bank Accounts API to add detail about which bank account each settlement
        was made to.


        For information about migrating your code to the Payouts API, see
        [Migrate from the Square Settlements API

        ](https://developer.squareup.com/docs/migrate-from-v1/guides/v1-settlements)
    Sites:
      name: Sites
      summary: Get details about Square Online sites that belong to Square sellers.
      description: >-

        Square sellers use Square Online to build eCommerce websites. The Sites
        API lets you get basic details about Square Online sites, such as the
        site ID, title, and domain. You can use the Sites API with the Snippets
        API to manage snippets that extend Square Online features.

         __Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).

         For more information, see the following guide:
         - [Sites](https://developer.squareup.com/docs/sites-api/overview)
    Snippets:
      name: Snippets
      summary: Manage snippets for Square Online sites.
      description: >-

        The Snippets API lets you manage snippets that add custom functionality
        to Square Online sites. A snippet is HTML, CSS, and JavaScript that is
        injected into the `head` element of all pages on a site, except for
        checkout pages. You can use the Snippets API to create applications that
        help meet the many needs of Square sellers.

         __Note:__ Square Online APIs are publicly available as part of an early access program. For more information, see [Early access program for Square Online APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).

         For more information, see the following guide:
         - [Snippets](https://developer.squareup.com/docs/snippets-api/overview)
    Subscriptions:
      name: Subscriptions
      summary: Create and manage subscriptions.
      description: >-

        Subscriptions enable sellers to generate a reliable cash flow and
        recurring revenue to grow their businesses. Square offers the
        Subscriptions API for developers to embed subscription functionality in
        their applications. You first create a subscription plan using the
        Catalog API and then use the Subscriptions API to create and manage
        subscriptions. 


        For more information, see the following guides:
         - [Subscriptions](https://developer.squareup.com/docs/subscriptions/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Team:
      name: Team
      summary: >-
        Manage a roster of team members and pull employee data into accounting
        and payroll systems.
      description: >

        The Team API allows applications to manage team members and job
        definitions, which can be useful

        in payroll and accounting contexts.


        The Team API integrates closely with the Labor API for timecard
        management.


        For more information, see the following guide:
         - [Team](https://developer.squareup.com/docs/team/overview)
         - [Square Webhooks](https://developer.squareup.com/docs/webhooks-overview)
    Terminal:
      name: Terminal
      summary: Requests a checkout from a paired Square Terminal.
      description: >-

        The Terminal API allows you to manage sending and receiving requests and
        responses from a paired Square Terminal. For a Terminal checkout,
        refund, or action, you can create a request, check its status, cancel
        the request, search for in-process requests, and get the results of the
        request after it is completed. In the current implementation, refunds
        are only supported for Interac debit cards in Canada.


        For more information, see the following guides:
         - [Terminal](https://developer.squareup.com/docs/terminal-api/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    Transactions:
      name: Transactions
      summary: Deprecated - Use the Orders and Payments APIs instead.
      description: >-

        Prior to 2019/08/15, the Transactions API was the way to take online
        payments. Going forward, the Payments API 

        and Refunds API (together with the Orders API) replace the Transactions
        API. For information about migrating your code to the Payments API, see
        [Migrate from
        Transactions](https://developer.squareup.com/docs/payments-api/migrate-from-transactions-api)
    V1Webhooks:
      name: V1Webhooks
      summary: Deprecated - Use V2 Webhooks.
      description: >-

        If you are working with V1 (deprecated) webhooks, you use the Webhooks
        API to subscribe to events for each seller you are interested in
        receiving events for.


        If you are working with V2 webhooks, you do not need to use this API.

        Instead, you subscribe to events using the [Developer Dashboard](/apps)
        or the [Webhook Subscriptions
        API](/reference/square/webhook-subscriptions-api).

        Learn how to subscribe to V2 webhooks using the
        [dashboard](/docs/webhooks/step2subscribe) or the
        [API](/docs/webhooks/webhook-subscriptions-api).
    Vendors:
      name: Vendors
      summary: Manages a seller's suppliers.
      description: >-
        The Vendors API allows applications to create, retrieve, and update
        vendors as suppliers to a seller.


        For more information, see the following guides:
         - [Vendors](https://developer.squareup.com/docs/vendors-api/overview)
         - [Square Webhooks Overview](https://developer.squareup.com/docs/webhooks-overview)
    WebhookSubscriptions:
      name: Webhook Subscriptions
      summary: Create and manage webhook subscriptions.
      description: >-

        The Webhook Subscriptions API allows you to create, retrieve, update,
        and delete webhook subscriptions. Because Webhook subscriptions are
        owned by the application and not any one seller, you cannot use OAuth
        Access Tokens with the Webhook Subscriptions API. You must use the
        applications [personal access token](/docs/build-basics/access-tokens).


        For more information, see the following guide the following guide:
         - [Webhook Subscriptions](https://developer.squareup.com/docs/webhooks/webhook-subscriptions-api)
  x-categories:
    Commerce:
      name: Commerce
      summary: >-
        Process orders, manage catalogs, track inventory, book reservations, and
        manage vendors. 
      description: ''
      apis:
        - '#/components/x-apis/Orders'
        - '#/components/x-apis/OrderCustomAttributes'
        - '#/components/x-apis/Catalog'
        - '#/components/x-apis/Inventory'
        - '#/components/x-apis/Bookings'
        - '#/components/x-apis/Booking Custom Attributes'
        - '#/components/x-apis/Vendors'
        - '#/components/x-apis/Sites'
        - '#/components/x-apis/Snippets'
        - '#/components/x-apis/Cash Drawers'
    Customers:
      name: Customers
      summary: >-
        Securely manage customer data and integrate engagement features to
        increase repeat business and attract new customers.
      description: |+

      apis:
        - '#/components/x-apis/Customers'
        - '#/components/x-apis/CustomerCustomAttributes'
        - '#/components/x-apis/CustomerGroups'
        - '#/components/x-apis/CustomerSegments'
        - '#/components/x-apis/Loyalty'
        - '#/components/x-apis/GiftCards'
        - '#/components/x-apis/GiftCardActivities'
    Dev Essentials:
      name: Dev Essentials
      summary: >-
        Authenticate your app, provide secure delegated access to Square account
        data, and manage webhook subscriptions.
      description: ''
      apis:
        - '#/components/x-apis/OAuth'
        - '#/components/x-apis/WebhookSubscriptions'
        - '#/components/x-apis/Events'
    Merchants:
      name: Merchants
      summary: >-
        Manage a seller's core business information used for business, and
        suppliers.
      description: ''
      apis:
        - '#/components/x-apis/Merchants'
        - '#/components/x-apis/MerchantCustomAttributes'
        - '#/components/x-apis/Locations'
        - '#/components/x-apis/LocationCustomAttributes'
    Payments:
      name: Payments
      summary: >-
        Take payments, process refunds, manage disputes, enable subscriptions,
        and get paid for your sales.
      description: |+

      apis:
        - '#/components/x-apis/Payments'
        - '#/components/x-apis/Refunds'
        - '#/components/x-apis/Checkout'
        - '#/components/x-apis/Terminal'
        - '#/components/x-apis/Disputes'
        - '#/components/x-apis/Invoices'
        - '#/components/x-apis/Cards'
        - '#/components/x-apis/Subscriptions'
        - '#/components/x-apis/BankAccounts'
        - '#/components/x-apis/Payouts'
        - '#/components/x-apis/MobileAuthorization'
        - '#/components/x-apis/Devices'
        - '#/components/x-apis/ApplePay'
    Staff:
      name: Staff
      summary: Manage team members and jobs, and track shift hours.
      description: ''
      apis:
        - '#/components/x-apis/Labor'
        - '#/components/x-apis/Team'
  x-categories-order:
    - Dev Essentials
    - Payments
    - Commerce
    - Customers
    - Staff
    - Merchants
  x-v1-api-mappings:
    V1Employees:
      V1CreateEmployee: Employees
      V1CreateEmployeeRole: Employees
      V1CreateTimecard: Labor
      V1DeleteTimecard: Labor
      V1ListCashDrawerShifts: CashDrawers
      V1ListEmployeeRoles: Employees
      V1ListEmployees: Employees
      V1ListTimecardEvents: Labor
      V1ListTimecards: Labor
      V1RetrieveCashDrawerShift: CashDrawers
      V1RetrieveEmployee: Employees
      V1RetrieveEmployeeRole: Employees
      V1RetrieveTimecard: Labor
      V1UpdateEmployee: Employees
      V1UpdateEmployeeRole: Employees
      V1UpdateTimecard: Labor
    V1Items:
      V1AdjustInventory: Inventory
      V1ApplyFee: Catalog
      V1ApplyModifierList: Catalog
      V1CreateCategory: Catalog
      V1CreateDiscount: Catalog
      V1CreateFee: Catalog
      V1CreateItem: Catalog
      V1CreateModifierList: Catalog
      V1CreateModifierOption: Catalog
      V1CreatePage: Catalog
      V1CreateVariation: Catalog
      V1DeleteCategory: Catalog
      V1DeleteDiscount: Catalog
      V1DeleteFee: Catalog
      V1DeleteItem: Catalog
      V1DeleteModifierList: Catalog
      V1DeleteModifierOption: Catalog
      V1DeletePage: Catalog
      V1DeletePageCell: Catalog
      V1DeleteVariation: Catalog
      V1ListCategories: Catalog
      V1ListDiscounts: Catalog
      V1ListFees: Catalog
      V1ListInventory: Inventory
      V1ListItems: Catalog
      V1ListModifierLists: Catalog
      V1ListPages: Catalog
      V1RemoveFee: Catalog
      V1RemoveModifierList: Catalog
      V1RetrieveItem: Catalog
      V1RetrieveModifierList: Catalog
      V1UpdateCategory: Catalog
      V1UpdateDiscount: Catalog
      V1UpdateFee: Catalog
      V1UpdateItem: Catalog
      V1UpdateModifierList: Catalog
      V1UpdateModifierOption: Catalog
      V1UpdatePage: Catalog
      V1UpdatePageCell: Catalog
      V1UpdateVariation: Catalog
      V1UploadItemImage: Catalog
    V1Locations:
      V1ListLocations: Locations
      V1RetrieveBusiness: Merchants
    V1Transactions:
      V1CreateRefund: Refunds
      V1ListBankAccounts: BankAccounts
      V1ListPayments: Payments
      V1ListRefunds: Refunds
      V1ListSettlements: Settlements
      V1RetrieveBankAccount: BankAccounts
      V1RetrievePayment: Payments
      V1RetrieveSettlement: Settlements
    V1Webhooks:
      V1ListWebhooks: V1Webhooks
      V1UpdateWebhooks: V1Webhooks
paths:
  /mobile/authorization-code:
    post:
      tags:
        - MobileAuthorization
      summary: CreateMobileAuthorizationCode
      operationId: CreateMobileAuthorizationCode
      description: >-
        Generates code to authorize a mobile application to connect to a Square
        card reader.


        Authorization codes are one-time-use codes and expire 60 minutes after
        being issued.


        __Important:__ The `Authorization` header you provide to this endpoint
        must have the following format:


        ```

        Authorization: Bearer ACCESS_TOKEN

        ```


        Replace `ACCESS_TOKEN` with a

        [valid production authorization
        credential](https://developer.squareup.com/docs/build-basics/access-tokens).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE_IN_PERSON
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMobileAuthorizationCodeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMobileAuthorizationCodeResponse'
  /oauth2/revoke:
    post:
      tags:
        - OAuth
      summary: RevokeToken
      operationId: RevokeToken
      description: >-
        Revokes an access token generated with the OAuth flow.


        If an account has more than one OAuth access token for your application,
        this

        endpoint revokes all of them, regardless of which token you specify. 


        __Important:__ The `Authorization` header for this endpoint must have
        the

        following format:


        ```

        Authorization: Client APPLICATION_SECRET

        ```


        Replace `APPLICATION_SECRET` with the application secret on the
        **OAuth**

        page for your application in the Developer Dashboard.
      x-release-status: PUBLIC
      security:
        - oauth2: null
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeTokenRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokeTokenResponse'
  /oauth2/token:
    post:
      tags:
        - OAuth
      summary: ObtainToken
      operationId: ObtainToken
      description: >-
        Returns an OAuth access token and a refresh token unless the 

        `short_lived` parameter is set to `true`, in which case the endpoint 

        returns only an access token.


        The `grant_type` parameter specifies the type of OAuth request. If 

        `grant_type` is `authorization_code`, you must include the
        authorization 

        code you received when a seller granted you authorization. If
        `grant_type` 

        is `refresh_token`, you must provide a valid refresh token. If you're
        using 

        an old version of the Square APIs (prior to March 13, 2019),
        `grant_type` 

        can be `migration_token` and you must provide a valid migration token.


        You can use the `scopes` parameter to limit the set of permissions
        granted 

        to the access token and refresh token. You can use the `short_lived`
        parameter 

        to create an access token that expires in 24 hours.


        __Note:__ OAuth tokens should be encrypted and stored on a secure
        server. 

        Application clients should never interact directly with OAuth tokens.
      x-release-status: PUBLIC
      security: []
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObtainTokenRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObtainTokenResponse'
  /oauth2/token/status:
    post:
      tags:
        - OAuth
      summary: RetrieveTokenStatus
      operationId: RetrieveTokenStatus
      description: >-
        Returns information about an [OAuth access
        token](https://developer.squareup.com/docs/build-basics/access-tokens#get-an-oauth-access-token)
        or an applications [personal access
        token](https://developer.squareup.com/docs/build-basics/access-tokens#get-a-personal-access-token).


        Add the access token to the Authorization header of the request.


        __Important:__ The `Authorization` header you provide to this endpoint
        must have the following format:


        ```

        Authorization: Bearer ACCESS_TOKEN

        ```


        where `ACCESS_TOKEN` is a

        [valid production authorization
        credential](https://developer.squareup.com/docs/build-basics/access-tokens).


        If the access token is expired or not a valid access token, the endpoint
        returns an `UNAUTHORIZED` error.
      x-release-status: PUBLIC
      security:
        - oauth2: []
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveTokenStatusResponse'
  /v1/{location_id}/orders:
    get:
      tags:
        - V1Transactions
      summary: V1ListOrders
      operationId: V1ListOrders
      description: Provides summary information for a merchant's online store orders.
      x-release-status: DEPRECATED
      x-visibility: SDK_ONLY
      deprecated: true
      x-deprecation: {}
      security:
        - oauth2:
            - ORDERS_READ
      parameters:
        - name: location_id
          description: The ID of the location to list online store orders for.
          schema:
            type: string
          in: path
          required: true
        - name: order
          description: The order in which payments are listed in the response.
          schema:
            $ref: '#/components/schemas/SortOrder'
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of payments to return in a single response. This
            value cannot exceed 200.
          schema:
            type: integer
          in: query
          required: false
        - name: batch_token
          description: |-
            A pagination cursor to retrieve the next set of results for your
            original query to the endpoint.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/V1Order'
  /v1/{location_id}/orders/{order_id}:
    get:
      tags:
        - V1Transactions
      summary: V1RetrieveOrder
      operationId: V1RetrieveOrder
      description: >-
        Provides comprehensive information for a single online store order,
        including the order's history.
      x-release-status: DEPRECATED
      x-visibility: SDK_ONLY
      deprecated: true
      x-deprecation: {}
      security:
        - oauth2:
            - ORDERS_READ
      parameters:
        - name: location_id
          description: The ID of the order's associated location.
          schema:
            type: string
          in: path
          required: true
        - name: order_id
          description: >-
            The order's Square-issued ID. You obtain this value from Order
            objects returned by the List Orders endpoint
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Order'
    put:
      tags:
        - V1Transactions
      summary: V1UpdateOrder
      operationId: V1UpdateOrder
      description: >-
        Updates the details of an online store order. Every update you perform
        on an order corresponds to one of three actions:
      x-release-status: DEPRECATED
      x-visibility: SDK_ONLY
      deprecated: true
      x-deprecation: {}
      security:
        - oauth2:
            - ORDERS_WRITE
      parameters:
        - name: location_id
          description: The ID of the order's associated location.
          schema:
            type: string
          in: path
          required: true
        - name: order_id
          description: >-
            The order's Square-issued ID. You obtain this value from Order
            objects returned by the List Orders endpoint
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1UpdateOrderRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1Order'
  /v2/apple-pay/domains:
    post:
      tags:
        - ApplePay
      summary: RegisterDomain
      operationId: RegisterDomain
      description: >-
        Activates a domain for use with Apple Pay on the Web and Square. A
        validation

        is performed on this domain by Apple to ensure that it is properly set
        up as

        an Apple Pay enabled domain.


        This endpoint provides an easy way for platform developers to bulk
        activate

        Apple Pay on the Web with Square for merchants using their platform.


        Note: You will need to host a valid domain verification file on your
        domain to support Apple Pay.  The

        current version of this file is always available at
        https://app.squareup.com/digital-wallets/apple-pay/apple-developer-merchantid-domain-association,

        and should be hosted at
        `.well_known/apple-developer-merchantid-domain-association` on your

        domain.  This file is subject to change; we strongly recommend checking
        for updates regularly and avoiding

        long-lived caches that might not keep in sync with the correct file
        version.


        To learn more about the Web Payments SDK and how to add Apple Pay, see
        [Take an Apple Pay
        Payment](https://developer.squareup.com/docs/web-payments/apple-pay).
      x-release-status: PUBLIC
      security:
        - oauth2: []
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterDomainRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterDomainResponse'
  /v2/bank-accounts:
    get:
      tags:
        - BankAccounts
      summary: ListBankAccounts
      operationId: ListBankAccounts
      description: >-
        Returns a list of [BankAccount](entity:BankAccount) objects linked to a
        Square account.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - BANK_ACCOUNTS_READ
      parameters:
        - name: cursor
          description: >-
            The pagination cursor returned by a previous call to this endpoint.

            Use it in the next `ListBankAccounts` request to retrieve the next
            set 

            of results.


            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            Upper limit on the number of bank accounts to return in the
            response. 

            Currently, 1000 is the largest supported limit. You can specify a
            limit 

            of up to 1000 bank accounts. This is also the default limit.
          schema:
            type: integer
          in: query
          required: false
        - name: location_id
          description: >-
            Location ID. You can specify this optional filter 

            to retrieve only the linked bank accounts belonging to a specific
            location.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBankAccountsResponse'
  /v2/bank-accounts/by-v1-id/{v1_bank_account_id}:
    get:
      tags:
        - BankAccounts
      summary: GetBankAccountByV1Id
      operationId: GetBankAccountByV1Id
      description: >-
        Returns details of a [BankAccount](entity:BankAccount) identified by V1
        bank account ID.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - BANK_ACCOUNTS_READ
      parameters:
        - name: v1_bank_account_id
          description: >-
            Connect V1 ID of the desired `BankAccount`. For more information,
            see 

            [Retrieve a bank account by using an ID issued by V1 Bank Accounts
            API](https://developer.squareup.com/docs/bank-accounts-api#retrieve-a-bank-account-by-using-an-id-issued-by-v1-bank-accounts-api).
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBankAccountByV1IdResponse'
  /v2/bank-accounts/{bank_account_id}:
    get:
      tags:
        - BankAccounts
      summary: GetBankAccount
      operationId: GetBankAccount
      description: |-
        Returns details of a [BankAccount](entity:BankAccount)
        linked to a Square account.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - BANK_ACCOUNTS_READ
      parameters:
        - name: bank_account_id
          description: Square-issued ID of the desired `BankAccount`.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBankAccountResponse'
  /v2/bookings:
    get:
      tags:
        - Bookings
      summary: ListBookings
      operationId: ListBookings
      description: >-
        Retrieve a collection of bookings.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_READ` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_READ
      parameters:
        - name: limit
          description: >-
            The maximum number of results per page to return in a paged
            response.
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: >-
            The pagination cursor from the preceding response to return the next
            page of the results. Do not set this when retrieving the first page
            of the results.
          schema:
            type: string
          in: query
          required: false
        - name: customer_id
          description: >-
            The [customer](entity:Customer) for whom to retrieve bookings. If
            this is not set, bookings for all customers are retrieved.
          schema:
            type: string
          in: query
          required: false
        - name: team_member_id
          description: >-
            The team member for whom to retrieve bookings. If this is not set,
            bookings of all members are retrieved.
          schema:
            type: string
          in: query
          required: false
        - name: location_id
          description: >-
            The location for which to retrieve bookings. If this is not set, all
            locations' bookings are retrieved.
          schema:
            type: string
          in: query
          required: false
        - name: start_at_min
          description: >-
            The RFC 3339 timestamp specifying the earliest of the start time. If
            this is not set, the current time is used.
          schema:
            type: string
          in: query
          required: false
        - name: start_at_max
          description: >-
            The RFC 3339 timestamp specifying the latest of the start time. If
            this is not set, the time of 31 days after `start_at_min` is used.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBookingsResponse'
    post:
      tags:
        - Bookings
      summary: CreateBooking
      operationId: CreateBooking
      description: >-
        Creates a booking.


        The required input must include the following:

        - `Booking.location_id`

        - `Booking.start_at`

        - `Booking.AppointmentSegment.team_member_id`

        - `Booking.AppointmentSegment.service_variation_id`

        - `Booking.AppointmentSegment.service_variation_version`


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_WRITE` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.


        For calls to this endpoint with seller-level permissions to succeed, the
        seller must have subscribed to *Appointments Plus*

        or *Appointments Premium*.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBookingRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBookingResponse'
  /v2/bookings/availability/search:
    post:
      tags:
        - Bookings
      summary: SearchAvailability
      operationId: SearchAvailability
      description: >-
        Searches for availabilities for booking.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_READ` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchAvailabilityRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchAvailabilityResponse'
  /v2/bookings/bulk-retrieve:
    post:
      tags:
        - Bookings
      summary: BulkRetrieveBookings
      operationId: BulkRetrieveBookings
      description: >-
        Bulk-Retrieves a list of bookings by booking IDs.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_READ` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkRetrieveBookingsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkRetrieveBookingsResponse'
  /v2/bookings/business-booking-profile:
    get:
      tags:
        - Bookings
      summary: RetrieveBusinessBookingProfile
      operationId: RetrieveBusinessBookingProfile
      description: Retrieves a seller's booking profile.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_BUSINESS_SETTINGS_READ
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveBusinessBookingProfileResponse'
  /v2/bookings/custom-attribute-definitions:
    get:
      tags:
        - BookingCustomAttributes
      summary: ListBookingCustomAttributeDefinitions
      operationId: ListBookingCustomAttributeDefinitions
      description: >-
        Get all bookings custom attribute definitions.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_READ` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_READ
      parameters:
        - name: limit
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ListBookingCustomAttributeDefinitionsResponse
    post:
      tags:
        - BookingCustomAttributes
      summary: CreateBookingCustomAttributeDefinition
      operationId: CreateBookingCustomAttributeDefinition
      description: >-
        Creates a bookings custom attribute definition.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_WRITE` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.


        For calls to this endpoint with seller-level permissions to succeed, the
        seller must have subscribed to *Appointments Plus*

        or *Appointments Premium*.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/CreateBookingCustomAttributeDefinitionRequest
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/CreateBookingCustomAttributeDefinitionResponse
  /v2/bookings/custom-attribute-definitions/{key}:
    delete:
      tags:
        - BookingCustomAttributes
      summary: DeleteBookingCustomAttributeDefinition
      operationId: DeleteBookingCustomAttributeDefinition
      description: >-
        Deletes a bookings custom attribute definition.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_WRITE` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.


        For calls to this endpoint with seller-level permissions to succeed, the
        seller must have subscribed to *Appointments Plus*

        or *Appointments Premium*.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_WRITE
      parameters:
        - name: key
          description: The key of the custom attribute definition to delete.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/DeleteBookingCustomAttributeDefinitionResponse
    get:
      tags:
        - BookingCustomAttributes
      summary: RetrieveBookingCustomAttributeDefinition
      operationId: RetrieveBookingCustomAttributeDefinition
      description: >-
        Retrieves a bookings custom attribute definition.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_READ` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_READ
      parameters:
        - name: key
          description: >-
            The key of the custom attribute definition to retrieve. If the
            requesting application

            is not the definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
        - name: version
          description: >-
            The current version of the custom attribute definition, which is
            used for strongly consistent

            reads to guarantee that you receive the most up-to-date data. When
            included in the request,

            Square returns the specified version or a higher version if one
            exists. If the specified version

            is higher than the current version, Square returns a `BAD_REQUEST`
            error.
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/RetrieveBookingCustomAttributeDefinitionResponse
    put:
      tags:
        - BookingCustomAttributes
      summary: UpdateBookingCustomAttributeDefinition
      operationId: UpdateBookingCustomAttributeDefinition
      description: >-
        Updates a bookings custom attribute definition.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_WRITE` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.


        For calls to this endpoint with seller-level permissions to succeed, the
        seller must have subscribed to *Appointments Plus*

        or *Appointments Premium*.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_WRITE
      parameters:
        - name: key
          description: The key of the custom attribute definition to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/UpdateBookingCustomAttributeDefinitionRequest
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/UpdateBookingCustomAttributeDefinitionResponse
  /v2/bookings/custom-attributes/bulk-delete:
    post:
      tags:
        - BookingCustomAttributes
      summary: BulkDeleteBookingCustomAttributes
      operationId: BulkDeleteBookingCustomAttributes
      description: >-
        Bulk deletes bookings custom attributes.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_WRITE` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.


        For calls to this endpoint with seller-level permissions to succeed, the
        seller must have subscribed to *Appointments Plus*

        or *Appointments Premium*.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteBookingCustomAttributesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkDeleteBookingCustomAttributesResponse'
  /v2/bookings/custom-attributes/bulk-upsert:
    post:
      tags:
        - BookingCustomAttributes
      summary: BulkUpsertBookingCustomAttributes
      operationId: BulkUpsertBookingCustomAttributes
      description: >-
        Bulk upserts bookings custom attributes.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_WRITE` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.


        For calls to this endpoint with seller-level permissions to succeed, the
        seller must have subscribed to *Appointments Plus*

        or *Appointments Premium*.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpsertBookingCustomAttributesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpsertBookingCustomAttributesResponse'
  /v2/bookings/location-booking-profiles:
    get:
      tags:
        - Bookings
      summary: ListLocationBookingProfiles
      operationId: ListLocationBookingProfiles
      description: Lists location booking profiles of a seller.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_BUSINESS_SETTINGS_READ
      parameters:
        - name: limit
          description: The maximum number of results to return in a paged response.
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: >-
            The pagination cursor from the preceding response to return the next
            page of the results. Do not set this when retrieving the first page
            of the results.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListLocationBookingProfilesResponse'
  /v2/bookings/location-booking-profiles/{location_id}:
    get:
      tags:
        - Bookings
      summary: RetrieveLocationBookingProfile
      operationId: RetrieveLocationBookingProfile
      description: Retrieves a seller's location booking profile.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_BUSINESS_SETTINGS_READ
      parameters:
        - name: location_id
          description: The ID of the location to retrieve the booking profile.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveLocationBookingProfileResponse'
  /v2/bookings/team-member-booking-profiles:
    get:
      tags:
        - Bookings
      summary: ListTeamMemberBookingProfiles
      operationId: ListTeamMemberBookingProfiles
      description: Lists booking profiles for team members.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_BUSINESS_SETTINGS_READ
      parameters:
        - name: bookable_only
          description: >-
            Indicates whether to include only bookable team members in the
            returned result (`true`) or not (`false`).
          schema:
            type: boolean
            default: false
          in: query
          required: false
        - name: limit
          description: The maximum number of results to return in a paged response.
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: >-
            The pagination cursor from the preceding response to return the next
            page of the results. Do not set this when retrieving the first page
            of the results.
          schema:
            type: string
          in: query
          required: false
        - name: location_id
          description: >-
            Indicates whether to include only team members enabled at the given
            location in the returned result.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTeamMemberBookingProfilesResponse'
  /v2/bookings/team-member-booking-profiles/bulk-retrieve:
    post:
      tags:
        - Bookings
      summary: BulkRetrieveTeamMemberBookingProfiles
      operationId: BulkRetrieveTeamMemberBookingProfiles
      description: Retrieves one or more team members' booking profiles.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_BUSINESS_SETTINGS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/BulkRetrieveTeamMemberBookingProfilesRequest
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/BulkRetrieveTeamMemberBookingProfilesResponse
  /v2/bookings/team-member-booking-profiles/{team_member_id}:
    get:
      tags:
        - Bookings
      summary: RetrieveTeamMemberBookingProfile
      operationId: RetrieveTeamMemberBookingProfile
      description: Retrieves a team member's booking profile.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_BUSINESS_SETTINGS_READ
      parameters:
        - name: team_member_id
          description: The ID of the team member to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveTeamMemberBookingProfileResponse'
  /v2/bookings/{booking_id}:
    get:
      tags:
        - Bookings
      summary: RetrieveBooking
      operationId: RetrieveBooking
      description: >-
        Retrieves a booking.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_READ` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_READ
      parameters:
        - name: booking_id
          description: >-
            The ID of the [Booking](entity:Booking) object representing the
            to-be-retrieved booking.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveBookingResponse'
    put:
      tags:
        - Bookings
      summary: UpdateBooking
      operationId: UpdateBooking
      description: >-
        Updates a booking.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_WRITE` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.


        For calls to this endpoint with seller-level permissions to succeed, the
        seller must have subscribed to *Appointments Plus*

        or *Appointments Premium*.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_WRITE
      parameters:
        - name: booking_id
          description: >-
            The ID of the [Booking](entity:Booking) object representing the
            to-be-updated booking.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBookingRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateBookingResponse'
  /v2/bookings/{booking_id}/cancel:
    post:
      tags:
        - Bookings
      summary: CancelBooking
      operationId: CancelBooking
      description: >-
        Cancels an existing booking.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_WRITE` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.


        For calls to this endpoint with seller-level permissions to succeed, the
        seller must have subscribed to *Appointments Plus*

        or *Appointments Premium*.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_WRITE
      parameters:
        - name: booking_id
          description: >-
            The ID of the [Booking](entity:Booking) object representing the
            to-be-cancelled booking.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelBookingRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelBookingResponse'
  /v2/bookings/{booking_id}/custom-attributes:
    get:
      tags:
        - BookingCustomAttributes
      summary: ListBookingCustomAttributes
      operationId: ListBookingCustomAttributes
      description: >-
        Lists a booking's custom attributes.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_READ` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_READ
      parameters:
        - name: booking_id
          description: The ID of the target [booking](entity:Booking).
          schema:
            type: string
          in: path
          required: true
        - name: limit
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request. For more

            information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: with_definitions
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of each

            custom attribute. Set this parameter to `true` to get the name and
            description of each custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          schema:
            type: boolean
            default: false
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBookingCustomAttributesResponse'
  /v2/bookings/{booking_id}/custom-attributes/{key}:
    delete:
      tags:
        - BookingCustomAttributes
      summary: DeleteBookingCustomAttribute
      operationId: DeleteBookingCustomAttribute
      description: >-
        Deletes a bookings custom attribute.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_WRITE` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.


        For calls to this endpoint with seller-level permissions to succeed, the
        seller must have subscribed to *Appointments Plus*

        or *Appointments Premium*.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_WRITE
      parameters:
        - name: booking_id
          description: The ID of the target [booking](entity:Booking).
          schema:
            type: string
          in: path
          required: true
        - name: key
          description: >-
            The key of the custom attribute to delete. This key must match the
            `key` of a custom

            attribute definition in the Square seller account. If the requesting
            application is not the

            definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteBookingCustomAttributeResponse'
    get:
      tags:
        - BookingCustomAttributes
      summary: RetrieveBookingCustomAttribute
      operationId: RetrieveBookingCustomAttribute
      description: >-
        Retrieves a bookings custom attribute.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_READ` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_READ` and `APPOINTMENTS_READ` for the OAuth scope.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_READ
      parameters:
        - name: booking_id
          description: The ID of the target [booking](entity:Booking).
          schema:
            type: string
          in: path
          required: true
        - name: key
          description: >-
            The key of the custom attribute to retrieve. This key must match the
            `key` of a custom

            attribute definition in the Square seller account. If the requesting
            application is not the

            definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
        - name: with_definition
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of

            the custom attribute. Set this parameter to `true` to get the name
            and description of the custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          schema:
            type: boolean
            default: false
          in: query
          required: false
        - name: version
          description: >-
            The current version of the custom attribute, which is used for
            strongly consistent reads to

            guarantee that you receive the most up-to-date data. When included
            in the request, Square

            returns the specified version or a higher version if one exists. If
            the specified version is

            higher than the current version, Square returns a `BAD_REQUEST`
            error.
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveBookingCustomAttributeResponse'
    put:
      tags:
        - BookingCustomAttributes
      summary: UpsertBookingCustomAttribute
      operationId: UpsertBookingCustomAttribute
      description: >-
        Upserts a bookings custom attribute.


        To call this endpoint with buyer-level permissions, set
        `APPOINTMENTS_WRITE` for the OAuth scope.

        To call this endpoint with seller-level permissions, set
        `APPOINTMENTS_ALL_WRITE` and `APPOINTMENTS_WRITE` for the OAuth scope.


        For calls to this endpoint with seller-level permissions to succeed, the
        seller must have subscribed to *Appointments Plus*

        or *Appointments Premium*.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - APPOINTMENTS_WRITE
      parameters:
        - name: booking_id
          description: The ID of the target [booking](entity:Booking).
          schema:
            type: string
          in: path
          required: true
        - name: key
          description: >-
            The key of the custom attribute to create or update. This key must
            match the `key` of a

            custom attribute definition in the Square seller account. If the
            requesting application is not

            the definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertBookingCustomAttributeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertBookingCustomAttributeResponse'
  /v2/cards:
    get:
      tags:
        - Cards
      summary: ListCards
      operationId: ListCards
      description: |-
        Retrieves a list of cards owned by the account making the request.
        A max of 25 cards will be returned.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters:
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for your original
            query.


            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
          schema:
            type: string
          in: query
          required: false
        - name: customer_id
          description: |-
            Limit results to cards associated with the customer supplied.
            By default, all cards owned by the merchant are returned.
          schema:
            type: string
          in: query
          required: false
        - name: include_disabled
          description: |-
            Includes disabled cards.
            By default, all enabled cards owned by the merchant are returned.
          schema:
            type: boolean
            default: false
          in: query
          required: false
        - name: reference_id
          description: Limit results to cards associated with the reference_id supplied.
          schema:
            type: string
          in: query
          required: false
        - name: sort_order
          description: >-
            Sorts the returned list by when the card was created with the
            specified order.

            This field defaults to ASC.
          schema:
            $ref: '#/components/schemas/SortOrder'
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCardsResponse'
    post:
      tags:
        - Cards
      summary: CreateCard
      operationId: CreateCard
      description: Adds a card on file to an existing merchant.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCardRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCardResponse'
      x-endpoint-errors:
        - error-code: CARD_DECLINED_VERIFICATION_REQUIRED
        - error-code: CARD_PROCESSING_NOT_ENABLED
        - error-code: CUSTOMER_NOT_FOUND
        - error-code: SOURCE_EXPIRED
        - error-code: SOURCE_USED
        - error-code: INVALID_CARD_DATA
  /v2/cards/{card_id}:
    get:
      tags:
        - Cards
      summary: RetrieveCard
      operationId: RetrieveCard
      description: Retrieves details for a specific Card.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters:
        - name: card_id
          description: Unique ID for the desired Card.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveCardResponse'
      x-endpoint-errors:
        - error-code: NOT_FOUND
  /v2/cards/{card_id}/disable:
    post:
      tags:
        - Cards
      summary: DisableCard
      operationId: DisableCard
      description: |-
        Disables the card, preventing any further updates or charges.
        Disabling an already disabled card is allowed but has no effect.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters:
        - name: card_id
          description: Unique ID for the desired Card.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisableCardResponse'
      x-endpoint-errors:
        - error-code: NOT_FOUND
  /v2/cash-drawers/shifts:
    get:
      tags:
        - CashDrawers
      summary: ListCashDrawerShifts
      operationId: ListCashDrawerShifts
      description: |-
        Provides the details for all of the cash drawer shifts for a location
        in a date range.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CASH_DRAWER_READ
      parameters:
        - name: location_id
          description: The ID of the location to query for a list of cash drawer shifts.
          schema:
            type: string
          in: query
          required: true
        - name: sort_order
          description: |-
            The order in which cash drawer shifts are listed in the response,
            based on their opened_at field. Default value: ASC
          schema:
            $ref: '#/components/schemas/SortOrder'
          in: query
          required: false
        - name: begin_time
          description: >-
            The inclusive start time of the query on opened_at, in ISO 8601
            format.
          schema:
            type: string
          in: query
          required: false
        - name: end_time
          description: >-
            The exclusive end date of the query on opened_at, in ISO 8601
            format.
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: |-
            Number of cash drawer shift events in a page of results (200 by
            default, 1000 max).
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: Opaque cursor for fetching the next page of results.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCashDrawerShiftsResponse'
  /v2/cash-drawers/shifts/{shift_id}:
    get:
      tags:
        - CashDrawers
      summary: RetrieveCashDrawerShift
      operationId: RetrieveCashDrawerShift
      description: >-
        Provides the summary details for a single cash drawer shift. See

        [ListCashDrawerShiftEvents](api-endpoint:CashDrawers-ListCashDrawerShiftEvents)
        for a list of cash drawer shift events.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CASH_DRAWER_READ
      parameters:
        - name: location_id
          description: The ID of the location to retrieve cash drawer shifts from.
          schema:
            type: string
          in: query
          required: true
        - name: shift_id
          description: The shift ID.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveCashDrawerShiftResponse'
  /v2/cash-drawers/shifts/{shift_id}/events:
    get:
      tags:
        - CashDrawers
      summary: ListCashDrawerShiftEvents
      operationId: ListCashDrawerShiftEvents
      description: Provides a paginated list of events for a single cash drawer shift.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CASH_DRAWER_READ
      parameters:
        - name: location_id
          description: The ID of the location to list cash drawer shifts for.
          schema:
            type: string
          in: query
          required: true
        - name: shift_id
          description: The shift ID.
          schema:
            type: string
          in: path
          required: true
        - name: limit
          description: |-
            Number of resources to be returned in a page of results (200 by
            default, 1000 max).
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: Opaque cursor for fetching the next page of results.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCashDrawerShiftEventsResponse'
  /v2/catalog/batch-delete:
    post:
      tags:
        - Catalog
      summary: BatchDeleteCatalogObjects
      operationId: BatchDeleteCatalogObjects
      description: >-
        Deletes a set of [CatalogItem](entity:CatalogItem)s based on the

        provided list of target IDs and returns a set of successfully deleted
        IDs in

        the response. Deletion is a cascading event such that all children of
        the

        targeted object are also deleted. For example, deleting a CatalogItem
        will

        also delete all of its
        [CatalogItemVariation](entity:CatalogItemVariation)

        children.


        `BatchDeleteCatalogObjects` succeeds even if only a portion of the
        targeted

        IDs can be deleted. The response will only include IDs that were

        actually deleted.


        To ensure consistency, only one delete request is processed at a time
        per seller account.

        While one (batch or non-batch) delete request is being processed, other
        (batched and non-batched)

        delete requests are rejected with the `429` error code.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ITEMS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchDeleteCatalogObjectsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchDeleteCatalogObjectsResponse'
  /v2/catalog/batch-retrieve:
    post:
      tags:
        - Catalog
      summary: BatchRetrieveCatalogObjects
      operationId: BatchRetrieveCatalogObjects
      description: >-
        Returns a set of objects based on the provided ID.

        Each [CatalogItem](entity:CatalogItem) returned in the set includes all
        of its

        child information including: all of its

        [CatalogItemVariation](entity:CatalogItemVariation) objects, references
        to

        its [CatalogModifierList](entity:CatalogModifierList) objects, and the
        ids of

        any [CatalogTax](entity:CatalogTax) objects that apply to it.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ITEMS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRetrieveCatalogObjectsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchRetrieveCatalogObjectsResponse'
  /v2/catalog/batch-upsert:
    post:
      tags:
        - Catalog
      summary: BatchUpsertCatalogObjects
      operationId: BatchUpsertCatalogObjects
      description: >-
        Creates or updates up to 10,000 target objects based on the provided

        list of objects. The target objects are grouped into batches and each
        batch is

        inserted/updated in an all-or-nothing manner. If an object within a
        batch is

        malformed in some way, or violates a database constraint, the entire
        batch

        containing that item will be disregarded. However, other batches in the
        same

        request may still succeed. Each batch may contain up to 1,000 objects,
        and

        batches will be processed in order as long as the total object count for
        the

        request (items, variations, modifier lists, discounts, and taxes) is no
        more

        than 10,000.


        To ensure consistency, only one update request is processed at a time
        per seller account.

        While one (batch or non-batch) update request is being processed, other
        (batched and non-batched)

        update requests are rejected with the `429` error code.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ITEMS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpsertCatalogObjectsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchUpsertCatalogObjectsResponse'
      x-endpoint-errors:
        - error-code: GENERIC_DECLINE
  /v2/catalog/images:
    post:
      tags:
        - Catalog
      summary: CreateCatalogImage
      operationId: CreateCatalogImage
      description: >-
        Uploads an image file to be represented by a
        [CatalogImage](entity:CatalogImage) object that can be linked to an
        existing

        [CatalogObject](entity:CatalogObject) instance. The resulting
        `CatalogImage` is unattached to any `CatalogObject` if the `object_id`

        is not specified.


        This `CreateCatalogImage` endpoint accepts HTTP multipart/form-data
        requests with a JSON part and an image file part in

        JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ITEMS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                request:
                  $ref: '#/components/schemas/CreateCatalogImageRequest'
                image_file:
                  type: string
                  format: binary
            encoding:
              image_file:
                contentType: image/jpeg
              request:
                contentType: application/json; charset=utf-8
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCatalogImageResponse'
      x-endpoint-errors:
        - error-code: GENERIC_DECLINE
  /v2/catalog/images/{image_id}:
    put:
      tags:
        - Catalog
      summary: UpdateCatalogImage
      operationId: UpdateCatalogImage
      description: >-
        Uploads a new image file to replace the existing one in the specified
        [CatalogImage](entity:CatalogImage) object.


        This `UpdateCatalogImage` endpoint accepts HTTP multipart/form-data
        requests with a JSON part and an image file part in

        JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB.
      x-release-status: BETA
      security:
        - oauth2:
            - ITEMS_WRITE
      parameters:
        - name: image_id
          description: >-
            The ID of the `CatalogImage` object to update the encapsulated image
            file.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                request:
                  $ref: '#/components/schemas/UpdateCatalogImageRequest'
                image_file:
                  type: string
                  format: binary
            encoding:
              image_file:
                contentType: image/jpeg
              request:
                contentType: application/json; charset=utf-8
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCatalogImageResponse'
  /v2/catalog/info:
    get:
      tags:
        - Catalog
      summary: CatalogInfo
      operationId: CatalogInfo
      description: |-
        Retrieves information about the Square Catalog API, such as batch size
        limits that can be used by the `BatchUpsertCatalogObjects` endpoint.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ITEMS_READ
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogInfoResponse'
  /v2/catalog/list:
    get:
      tags:
        - Catalog
      summary: ListCatalog
      operationId: ListCatalog
      description: >-
        Returns a list of all [CatalogObject](entity:CatalogObject)s of the
        specified types in the catalog.


        The `types` parameter is specified as a comma-separated list of the
        [CatalogObjectType](entity:CatalogObjectType) values,

        for example, "`ITEM`, `ITEM_VARIATION`, `MODIFIER`, `MODIFIER_LIST`,
        `CATEGORY`, `DISCOUNT`, `TAX`, `IMAGE`".


        __Important:__ ListCatalog does not return deleted catalog items. To
        retrieve

        deleted catalog items, use
        [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects)

        and set the `include_deleted_objects` attribute value to `true`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ITEMS_READ
      parameters:
        - name: cursor
          description: >-
            The pagination cursor returned in the previous response. Leave unset
            for an initial request.

            The page size is currently set to be 100.

            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
          schema:
            type: string
          in: query
          required: false
        - name: types
          description: >-
            An optional case-insensitive, comma-separated list of object types
            to retrieve.


            The valid values are defined in the
            [CatalogObjectType](entity:CatalogObjectType) enum, for example,

            `ITEM`, `ITEM_VARIATION`, `CATEGORY`, `DISCOUNT`, `TAX`,

            `MODIFIER`, `MODIFIER_LIST`, `IMAGE`, etc.


            If this is unspecified, the operation returns objects of all the top
            level types at the version

            of the Square API used to make the request. Object types that are
            nested onto other object types

            are not included in the defaults.


            At the current API version the default object types are:

            ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, 

            PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT,

            SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION,
            QUICK_AMOUNT_SETTINGS.
          schema:
            type: string
          in: query
          required: false
        - name: catalog_version
          description: >-
            The specific version of the catalog objects to be included in the
            response.

            This allows you to retrieve historical versions of objects. The
            specified version value is matched against

            the [CatalogObject](entity:CatalogObject)s' `version` attribute.  If
            not included, results will be from the

            current version of the catalog.
          schema:
            type: integer
            format: int64
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCatalogResponse'
  /v2/catalog/object:
    post:
      tags:
        - Catalog
      summary: UpsertCatalogObject
      operationId: UpsertCatalogObject
      description: >-
        Creates a new or updates the specified
        [CatalogObject](entity:CatalogObject).


        To ensure consistency, only one update request is processed at a time
        per seller account.

        While one (batch or non-batch) update request is being processed, other
        (batched and non-batched)

        update requests are rejected with the `429` error code.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ITEMS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertCatalogObjectRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertCatalogObjectResponse'
      x-endpoint-errors:
        - error-code: GENERIC_DECLINE
        - error-code: INVALID_LOCATION
  /v2/catalog/object/{object_id}:
    delete:
      tags:
        - Catalog
      summary: DeleteCatalogObject
      operationId: DeleteCatalogObject
      description: >-
        Deletes a single [CatalogObject](entity:CatalogObject) based on the

        provided ID and returns the set of successfully deleted IDs in the
        response.

        Deletion is a cascading event such that all children of the targeted
        object

        are also deleted. For example, deleting a
        [CatalogItem](entity:CatalogItem)

        will also delete all of its

        [CatalogItemVariation](entity:CatalogItemVariation) children.


        To ensure consistency, only one delete request is processed at a time
        per seller account.

        While one (batch or non-batch) delete request is being processed, other
        (batched and non-batched)

        delete requests are rejected with the `429` error code.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ITEMS_WRITE
      parameters:
        - name: object_id
          description: >-
            The ID of the catalog object to be deleted. When an object is
            deleted, other

            objects in the graph that depend on that object will be deleted as
            well (for example, deleting a

            catalog item will delete its catalog item variations).
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCatalogObjectResponse'
    get:
      tags:
        - Catalog
      summary: RetrieveCatalogObject
      operationId: RetrieveCatalogObject
      description: >-
        Returns a single [CatalogItem](entity:CatalogItem) as a

        [CatalogObject](entity:CatalogObject) based on the provided ID. The
        returned

        object includes all of the relevant [CatalogItem](entity:CatalogItem)

        information including:
        [CatalogItemVariation](entity:CatalogItemVariation)

        children, references to its

        [CatalogModifierList](entity:CatalogModifierList) objects, and the ids
        of

        any [CatalogTax](entity:CatalogTax) objects that apply to it.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ITEMS_READ
      parameters:
        - name: object_id
          description: The object ID of any type of catalog objects to be retrieved.
          schema:
            type: string
          in: path
          required: true
        - name: include_related_objects
          description: >-
            If `true`, the response will include additional objects that are
            related to the

            requested objects. Related objects are defined as any objects
            referenced by ID by the results in the `objects` field

            of the response. These objects are put in the `related_objects`
            field. Setting this to `true` is

            helpful when the objects are needed for immediate display to a user.

            This process only goes one level deep. Objects referenced by the
            related objects will not be included. For example,


            if the `objects` field of the response contains a CatalogItem, its
            associated

            CatalogCategory objects, CatalogTax objects, CatalogImage objects
            and

            CatalogModifierLists will be returned in the `related_objects` field
            of the

            response. If the `objects` field of the response contains a
            CatalogItemVariation,

            its parent CatalogItem will be returned in the `related_objects`
            field of

            the response.


            Default value: `false`
          schema:
            type: boolean
            default: false
          in: query
          required: false
        - name: catalog_version
          description: >-
            Requests objects as of a specific version of the catalog. This
            allows you to retrieve historical

            versions of objects. The value to retrieve a specific version of an
            object can be found

            in the version field of [CatalogObject](entity:CatalogObject)s. If
            not included, results will

            be from the current version of the catalog.
          schema:
            type: integer
            format: int64
          in: query
          required: false
        - name: include_category_path_to_root
          description: >-
            Specifies whether or not to include the `path_to_root` list for each
            returned category instance. The `path_to_root` list consists

            of `CategoryPathToRootNode` objects and specifies the path that
            starts with the immediate parent category of the returned category

            and ends with its root category. If the returned category is a
            top-level category, the `path_to_root` list is empty and is not
            returned

            in the response payload.
          schema:
            type: boolean
            default: false
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveCatalogObjectResponse'
  /v2/catalog/search:
    post:
      tags:
        - Catalog
      summary: SearchCatalogObjects
      operationId: SearchCatalogObjects
      description: >-
        Searches for [CatalogObject](entity:CatalogObject) of any type by
        matching supported search attribute values,

        excluding custom attribute values on items or item variations, against
        one or more of the specified query filters.


        This (`SearchCatalogObjects`) endpoint differs from the
        [SearchCatalogItems](api-endpoint:Catalog-SearchCatalogItems)

        endpoint in the following aspects:


        - `SearchCatalogItems` can only search for items or item variations,
        whereas `SearchCatalogObjects` can search for any type of catalog
        objects.

        - `SearchCatalogItems` supports the custom attribute query filters to
        return items or item variations that contain custom attribute values,
        where `SearchCatalogObjects` does not.

        - `SearchCatalogItems` does not support the `include_deleted_objects`
        filter to search for deleted items or item variations, whereas
        `SearchCatalogObjects` does.

        - The both endpoints have different call conventions, including the
        query filter formats.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ITEMS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchCatalogObjectsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCatalogObjectsResponse'
  /v2/catalog/search-catalog-items:
    post:
      tags:
        - Catalog
      summary: SearchCatalogItems
      operationId: SearchCatalogItems
      description: >-
        Searches for catalog items or item variations by matching supported
        search attribute values, including

        custom attribute values, against one or more of the specified query
        filters.


        This (`SearchCatalogItems`) endpoint differs from the
        [SearchCatalogObjects](api-endpoint:Catalog-SearchCatalogObjects)

        endpoint in the following aspects:


        - `SearchCatalogItems` can only search for items or item variations,
        whereas `SearchCatalogObjects` can search for any type of catalog
        objects.

        - `SearchCatalogItems` supports the custom attribute query filters to
        return items or item variations that contain custom attribute values,
        where `SearchCatalogObjects` does not.

        - `SearchCatalogItems` does not support the `include_deleted_objects`
        filter to search for deleted items or item variations, whereas
        `SearchCatalogObjects` does.

        - The both endpoints use different call conventions, including the query
        filter formats.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ITEMS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchCatalogItemsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCatalogItemsResponse'
  /v2/catalog/update-item-modifier-lists:
    post:
      tags:
        - Catalog
      summary: UpdateItemModifierLists
      operationId: UpdateItemModifierLists
      description: >-
        Updates the [CatalogModifierList](entity:CatalogModifierList) objects

        that apply to the targeted [CatalogItem](entity:CatalogItem) without
        having

        to perform an upsert on the entire item.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ITEMS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateItemModifierListsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateItemModifierListsResponse'
  /v2/catalog/update-item-taxes:
    post:
      tags:
        - Catalog
      summary: UpdateItemTaxes
      operationId: UpdateItemTaxes
      description: |-
        Updates the [CatalogTax](entity:CatalogTax) objects that apply to the
        targeted [CatalogItem](entity:CatalogItem) without having to perform an
        upsert on the entire item.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ITEMS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateItemTaxesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateItemTaxesResponse'
  /v2/customers:
    get:
      tags:
        - Customers
      summary: ListCustomers
      operationId: ListCustomers
      description: >-
        Lists customer profiles associated with a Square account.


        Under normal operating conditions, newly created or updated customer
        profiles become available

        for the listing operation in well under 30 seconds. Occasionally,
        propagation of the new or updated

        profiles can take closer to one minute or longer, especially during
        network incidents and outages.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
      parameters:
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for your
            original query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to return in a single page. This limit
            is advisory. The response might contain more or fewer results.

            If the specified limit is less than 1 or greater than 100, Square
            returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The
            default value is 100.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: integer
          in: query
          required: false
        - name: sort_field
          description: |-
            Indicates how customers should be sorted.

            The default value is `DEFAULT`.
          schema:
            $ref: '#/components/schemas/CustomerSortField'
          in: query
          required: false
        - name: sort_order
          description: |-
            Indicates whether customers should be sorted in ascending (`ASC`) or
            descending (`DESC`) order.

            The default value is `ASC`.
          schema:
            $ref: '#/components/schemas/SortOrder'
          in: query
          required: false
        - name: count
          description: >-
            Indicates whether to return the total count of customers in the
            `count` field of the response.


            The default value is `false`.
          schema:
            type: boolean
            default: false
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomersResponse'
    post:
      tags:
        - Customers
      summary: CreateCustomer
      operationId: CreateCustomer
      description: >-
        Creates a new customer for a business.


        You must provide at least one of the following values in your request to
        this

        endpoint:


        - `given_name`

        - `family_name`

        - `company_name`

        - `email_address`

        - `phone_number`
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCustomerResponse'
      x-endpoint-errors:
        - error-code: INVALID_EMAIL_ADDRESS
        - error-code: INVALID_PHONE_NUMBER
        - error-code: INVALID_TIME
        - error-code: VALUE_TOO_LONG
  /v2/customers/bulk-create:
    post:
      tags:
        - Customers
      summary: BulkCreateCustomers
      operationId: BulkCreateCustomers
      description: >-
        Creates multiple [customer profiles](entity:Customer) for a business.


        This endpoint takes a map of individual create requests and returns a
        map of responses.


        You must provide at least one of the following values in each create
        request:


        - `given_name`

        - `family_name`

        - `company_name`

        - `email_address`

        - `phone_number`
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkCreateCustomersRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkCreateCustomersResponse'
  /v2/customers/bulk-delete:
    post:
      tags:
        - Customers
      summary: BulkDeleteCustomers
      operationId: BulkDeleteCustomers
      description: >-
        Deletes multiple customer profiles.


        The endpoint takes a list of customer IDs and returns a map of
        responses.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteCustomersRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkDeleteCustomersResponse'
  /v2/customers/bulk-retrieve:
    post:
      tags:
        - Customers
      summary: BulkRetrieveCustomers
      operationId: BulkRetrieveCustomers
      description: >-
        Retrieves multiple customer profiles.


        This endpoint takes a list of customer IDs and returns a map of
        responses.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkRetrieveCustomersRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkRetrieveCustomersResponse'
  /v2/customers/bulk-update:
    post:
      tags:
        - Customers
      summary: BulkUpdateCustomers
      operationId: BulkUpdateCustomers
      description: >-
        Updates multiple customer profiles.


        This endpoint takes a map of individual update requests and returns a
        map of responses.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpdateCustomersRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpdateCustomersResponse'
  /v2/customers/custom-attribute-definitions:
    get:
      tags:
        - CustomerCustomAttributes
      summary: ListCustomerCustomAttributeDefinitions
      operationId: ListCustomerCustomAttributeDefinitions
      description: >-
        Lists the customer-related [custom attribute
        definitions](entity:CustomAttributeDefinition) that belong to a Square
        seller account.


        When all response pages are retrieved, the results include all custom
        attribute definitions

        that are visible to the requesting application, including those that are
        created by other

        applications and set to `VISIBILITY_READ_ONLY` or
        `VISIBILITY_READ_WRITE_VALUES`. Note that

        seller-defined custom attributes (also known as custom fields) are
        always set to `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
      parameters:
        - name: limit
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ListCustomerCustomAttributeDefinitionsResponse
    post:
      tags:
        - CustomerCustomAttributes
      summary: CreateCustomerCustomAttributeDefinition
      operationId: CreateCustomerCustomAttributeDefinition
      description: >-
        Creates a customer-related [custom attribute
        definition](entity:CustomAttributeDefinition) for a Square seller
        account.

        Use this endpoint to define a custom attribute that can be associated
        with customer profiles.


        A custom attribute definition specifies the `key`, `visibility`,
        `schema`, and other properties

        for a custom attribute. After the definition is created, you can call

        [UpsertCustomerCustomAttribute](api-endpoint:CustomerCustomAttributes-UpsertCustomerCustomAttribute)
        or

        [BulkUpsertCustomerCustomAttributes](api-endpoint:CustomerCustomAttributes-BulkUpsertCustomerCustomAttributes)

        to set the custom attribute for customer profiles in the seller's
        Customer Directory.


        Sellers can view all custom attributes in exported customer data,
        including those set to

        `VISIBILITY_HIDDEN`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/CreateCustomerCustomAttributeDefinitionRequest
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/CreateCustomerCustomAttributeDefinitionResponse
  /v2/customers/custom-attribute-definitions/{key}:
    delete:
      tags:
        - CustomerCustomAttributes
      summary: DeleteCustomerCustomAttributeDefinition
      operationId: DeleteCustomerCustomAttributeDefinition
      description: >-
        Deletes a customer-related [custom attribute
        definition](entity:CustomAttributeDefinition) from a Square seller
        account.


        Deleting a custom attribute definition also deletes the corresponding
        custom attribute from

        all customer profiles in the seller's Customer Directory.


        Only the definition owner can delete a custom attribute definition.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters:
        - name: key
          description: The key of the custom attribute definition to delete.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/DeleteCustomerCustomAttributeDefinitionResponse
    get:
      tags:
        - CustomerCustomAttributes
      summary: RetrieveCustomerCustomAttributeDefinition
      operationId: RetrieveCustomerCustomAttributeDefinition
      description: >-
        Retrieves a customer-related [custom attribute
        definition](entity:CustomAttributeDefinition) from a Square seller
        account.


        To retrieve a custom attribute definition created by another
        application, the `visibility`

        setting must be `VISIBILITY_READ_ONLY` or
        `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom
        attributes

        (also known as custom fields) are always set to
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
      parameters:
        - name: key
          description: >-
            The key of the custom attribute definition to retrieve. If the
            requesting application

            is not the definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
        - name: version
          description: >-
            The current version of the custom attribute definition, which is
            used for strongly consistent

            reads to guarantee that you receive the most up-to-date data. When
            included in the request,

            Square returns the specified version or a higher version if one
            exists. If the specified version

            is higher than the current version, Square returns a `BAD_REQUEST`
            error.
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/RetrieveCustomerCustomAttributeDefinitionResponse
    put:
      tags:
        - CustomerCustomAttributes
      summary: UpdateCustomerCustomAttributeDefinition
      operationId: UpdateCustomerCustomAttributeDefinition
      description: >-
        Updates a customer-related [custom attribute
        definition](entity:CustomAttributeDefinition) for a Square seller
        account.


        Use this endpoint to update the following fields: `name`, `description`,
        `visibility`, or the

        `schema` for a `Selection` data type.


        Only the definition owner can update a custom attribute definition. Note
        that sellers can view

        all custom attributes in exported customer data, including those set to
        `VISIBILITY_HIDDEN`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters:
        - name: key
          description: The key of the custom attribute definition to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/UpdateCustomerCustomAttributeDefinitionRequest
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/UpdateCustomerCustomAttributeDefinitionResponse
  /v2/customers/custom-attributes/bulk-upsert:
    post:
      tags:
        - CustomerCustomAttributes
      summary: BulkUpsertCustomerCustomAttributes
      operationId: BulkUpsertCustomerCustomAttributes
      description: >-
        Creates or updates [custom attributes](entity:CustomAttribute) for
        customer profiles as a bulk operation.


        Use this endpoint to set the value of one or more custom attributes for
        one or more customer profiles.

        A custom attribute is based on a custom attribute definition in a Square
        seller account, which is

        created using the
        [CreateCustomerCustomAttributeDefinition](api-endpoint:CustomerCustomAttributes-CreateCustomerCustomAttributeDefinition)
        endpoint.


        This `BulkUpsertCustomerCustomAttributes` endpoint accepts a map of 1 to
        25 individual upsert

        requests and returns a map of individual upsert responses. Each upsert
        request has a unique ID

        and provides a customer ID and custom attribute. Each upsert response is
        returned with the ID

        of the corresponding request.


        To create or update a custom attribute owned by another application, the
        `visibility` setting

        must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom
        attributes

        (also known as custom fields) are always set to
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpsertCustomerCustomAttributesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/BulkUpsertCustomerCustomAttributesResponse
  /v2/customers/groups:
    get:
      tags:
        - CustomerGroups
      summary: ListCustomerGroups
      operationId: ListCustomerGroups
      description: Retrieves the list of customer groups of a business.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
      parameters:
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for your
            original query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to return in a single page. This limit
            is advisory. The response might contain more or fewer results.

            If the limit is less than 1 or greater than 50, Square returns a
            `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The default value
            is 50.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomerGroupsResponse'
    post:
      tags:
        - CustomerGroups
      summary: CreateCustomerGroup
      operationId: CreateCustomerGroup
      description: |-
        Creates a new customer group for a business.

        The request must include the `name` value of the group.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerGroupRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCustomerGroupResponse'
  /v2/customers/groups/{group_id}:
    delete:
      tags:
        - CustomerGroups
      summary: DeleteCustomerGroup
      operationId: DeleteCustomerGroup
      description: Deletes a customer group as identified by the `group_id` value.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters:
        - name: group_id
          description: The ID of the customer group to delete.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCustomerGroupResponse'
    get:
      tags:
        - CustomerGroups
      summary: RetrieveCustomerGroup
      operationId: RetrieveCustomerGroup
      description: >-
        Retrieves a specific customer group as identified by the `group_id`
        value.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
      parameters:
        - name: group_id
          description: The ID of the customer group to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveCustomerGroupResponse'
    put:
      tags:
        - CustomerGroups
      summary: UpdateCustomerGroup
      operationId: UpdateCustomerGroup
      description: Updates a customer group as identified by the `group_id` value.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters:
        - name: group_id
          description: The ID of the customer group to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerGroupRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCustomerGroupResponse'
  /v2/customers/search:
    post:
      tags:
        - Customers
      summary: SearchCustomers
      operationId: SearchCustomers
      description: >-
        Searches the customer profiles associated with a Square account using
        one or more supported query filters.


        Calling `SearchCustomers` without any explicit query filter returns all

        customer profiles ordered alphabetically based on `given_name` and

        `family_name`.


        Under normal operating conditions, newly created or updated customer
        profiles become available

        for the search operation in well under 30 seconds. Occasionally,
        propagation of the new or updated

        profiles can take closer to one minute or longer, especially during
        network incidents and outages.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchCustomersRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchCustomersResponse'
  /v2/customers/segments:
    get:
      tags:
        - CustomerSegments
      summary: ListCustomerSegments
      operationId: ListCustomerSegments
      description: Retrieves the list of customer segments of a business.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
      parameters:
        - name: cursor
          description: >-
            A pagination cursor returned by previous calls to
            `ListCustomerSegments`.

            This cursor is used to retrieve the next set of query results.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to return in a single page. This limit
            is advisory. The response might contain more or fewer results.

            If the specified limit is less than 1 or greater than 50, Square
            returns a `400 VALUE_TOO_LOW` or `400 VALUE_TOO_HIGH` error. The
            default value is 50.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomerSegmentsResponse'
  /v2/customers/segments/{segment_id}:
    get:
      tags:
        - CustomerSegments
      summary: RetrieveCustomerSegment
      operationId: RetrieveCustomerSegment
      description: >-
        Retrieves a specific customer segment as identified by the `segment_id`
        value.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
      parameters:
        - name: segment_id
          description: The Square-issued ID of the customer segment.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveCustomerSegmentResponse'
  /v2/customers/{customer_id}:
    delete:
      tags:
        - Customers
      summary: DeleteCustomer
      operationId: DeleteCustomer
      description: >-
        Deletes a customer profile from a business.


        To delete a customer profile that was created by merging existing
        profiles, you must use the ID of the newly created profile.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters:
        - name: customer_id
          description: The ID of the customer to delete.
          schema:
            type: string
          in: path
          required: true
        - name: version
          description: >-
            The current version of the customer profile.


            As a best practice, you should include this parameter to enable
            [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)
            control.  For more information, see [Delete a customer
            profile](https://developer.squareup.com/docs/customers-api/use-the-api/keep-records#delete-customer-profile).
          schema:
            type: integer
            format: int64
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCustomerResponse'
    get:
      tags:
        - Customers
      summary: RetrieveCustomer
      operationId: RetrieveCustomer
      description: Returns details for a single customer.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
      parameters:
        - name: customer_id
          description: The ID of the customer to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveCustomerResponse'
    put:
      tags:
        - Customers
      summary: UpdateCustomer
      operationId: UpdateCustomer
      description: >-
        Updates a customer profile. This endpoint supports sparse updates, so
        only new or changed fields are required in the request.

        To add or update a field, specify the new value. To remove a field,
        specify `null`.


        To update a customer profile that was created by merging existing
        profiles, you must use the ID of the newly created profile.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters:
        - name: customer_id
          description: The ID of the customer to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCustomerRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateCustomerResponse'
      x-endpoint-errors:
        - error-code: INVALID_EMAIL_ADDRESS
        - error-code: INVALID_PHONE_NUMBER
        - error-code: INVALID_TIME
        - error-code: VALUE_TOO_LONG
  /v2/customers/{customer_id}/cards:
    post:
      tags:
        - Customers
      summary: CreateCustomerCard
      operationId: CreateCustomerCard
      description: >-
        Adds a card on file to an existing customer.


        As with charges, calls to `CreateCustomerCard` are idempotent. Multiple

        calls with the same card nonce return the same card record that was
        created

        with the provided nonce during the _first_ call.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2021-06-16'
        replacedBy: CreateCard
        guideUrl: >-
          https://developer.squareup.com/docs/customers-api/what-it-does#deprecated-createcustomercard-endpoint
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters:
        - name: customer_id
          description: The Square ID of the customer profile the card is linked to.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomerCardRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCustomerCardResponse'
      x-endpoint-errors:
        - error-code: CARD_EXPIRED
        - error-code: CARD_PROCESSING_NOT_ENABLED
        - error-code: CARD_TOKEN_EXPIRED
        - error-code: CARD_TOKEN_USED
        - error-code: INVALID_CARD
        - error-code: INVALID_CARD_DATA
        - error-code: INVALID_EXPIRATION
        - error-code: UNSUPPORTED_ENTRY_METHOD
        - error-code: VERIFY_AVS_FAILURE
        - error-code: VERIFY_CVV_FAILURE
  /v2/customers/{customer_id}/cards/{card_id}:
    delete:
      tags:
        - Customers
      summary: DeleteCustomerCard
      operationId: DeleteCustomerCard
      description: Removes a card on file from a customer.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2021-06-16'
        replacedBy: DisableCard
        guideUrl: >-
          https://developer.squareup.com/docs/customers-api/what-it-does#deprecated-deletecustomercard-endpoint
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters:
        - name: customer_id
          description: The ID of the customer that the card on file belongs to.
          schema:
            type: string
          in: path
          required: true
        - name: card_id
          description: The ID of the card on file to delete.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCustomerCardResponse'
  /v2/customers/{customer_id}/custom-attributes:
    get:
      tags:
        - CustomerCustomAttributes
      summary: ListCustomerCustomAttributes
      operationId: ListCustomerCustomAttributes
      description: >-
        Lists the [custom attributes](entity:CustomAttribute) associated with a
        customer profile.


        You can use the `with_definitions` query parameter to also retrieve
        custom attribute definitions

        in the same call.


        When all response pages are retrieved, the results include all custom
        attributes that are

        visible to the requesting application, including those that are owned by
        other applications

        and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
      parameters:
        - name: customer_id
          description: The ID of the target [customer profile](entity:Customer).
          schema:
            type: string
          in: path
          required: true
        - name: limit
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request. For more

            information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: with_definitions
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of each

            custom attribute. Set this parameter to `true` to get the name and
            description of each custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          schema:
            type: boolean
            default: false
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCustomerCustomAttributesResponse'
  /v2/customers/{customer_id}/custom-attributes/{key}:
    delete:
      tags:
        - CustomerCustomAttributes
      summary: DeleteCustomerCustomAttribute
      operationId: DeleteCustomerCustomAttribute
      description: >-
        Deletes a [custom attribute](entity:CustomAttribute) associated with a
        customer profile.


        To delete a custom attribute owned by another application, the
        `visibility` setting must be

        `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom
        attributes

        (also known as custom fields) are always set to
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters:
        - name: customer_id
          description: The ID of the target [customer profile](entity:Customer).
          schema:
            type: string
          in: path
          required: true
        - name: key
          description: >-
            The key of the custom attribute to delete. This key must match the
            `key` of a custom

            attribute definition in the Square seller account. If the requesting
            application is not the

            definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteCustomerCustomAttributeResponse'
    get:
      tags:
        - CustomerCustomAttributes
      summary: RetrieveCustomerCustomAttribute
      operationId: RetrieveCustomerCustomAttribute
      description: >-
        Retrieves a [custom attribute](entity:CustomAttribute) associated with a
        customer profile.


        You can use the `with_definition` query parameter to also retrieve the
        custom attribute definition

        in the same call.


        To retrieve a custom attribute owned by another application, the
        `visibility` setting must be

        `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that
        seller-defined custom attributes

        (also known as custom fields) are always set to
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
      parameters:
        - name: customer_id
          description: The ID of the target [customer profile](entity:Customer).
          schema:
            type: string
          in: path
          required: true
        - name: key
          description: >-
            The key of the custom attribute to retrieve. This key must match the
            `key` of a custom

            attribute definition in the Square seller account. If the requesting
            application is not the

            definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
        - name: with_definition
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of

            the custom attribute. Set this parameter to `true` to get the name
            and description of the custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          schema:
            type: boolean
            default: false
          in: query
          required: false
        - name: version
          description: >-
            The current version of the custom attribute, which is used for
            strongly consistent reads to

            guarantee that you receive the most up-to-date data. When included
            in the request, Square

            returns the specified version or a higher version if one exists. If
            the specified version is

            higher than the current version, Square returns a `BAD_REQUEST`
            error.
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveCustomerCustomAttributeResponse'
    post:
      tags:
        - CustomerCustomAttributes
      summary: UpsertCustomerCustomAttribute
      operationId: UpsertCustomerCustomAttribute
      description: >-
        Creates or updates a [custom attribute](entity:CustomAttribute) for a
        customer profile.


        Use this endpoint to set the value of a custom attribute for a specified
        customer profile.

        A custom attribute is based on a custom attribute definition in a Square
        seller account, which

        is created using the
        [CreateCustomerCustomAttributeDefinition](api-endpoint:CustomerCustomAttributes-CreateCustomerCustomAttributeDefinition)
        endpoint.


        To create or update a custom attribute owned by another application, the
        `visibility` setting

        must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom
        attributes

        (also known as custom fields) are always set to
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters:
        - name: customer_id
          description: The ID of the target [customer profile](entity:Customer).
          schema:
            type: string
          in: path
          required: true
        - name: key
          description: >-
            The key of the custom attribute to create or update. This key must
            match the `key` of a

            custom attribute definition in the Square seller account. If the
            requesting application is not

            the definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertCustomerCustomAttributeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertCustomerCustomAttributeResponse'
  /v2/customers/{customer_id}/groups/{group_id}:
    delete:
      tags:
        - Customers
      summary: RemoveGroupFromCustomer
      operationId: RemoveGroupFromCustomer
      description: |-
        Removes a group membership from a customer.

        The customer is identified by the `customer_id` value
        and the customer group is identified by the `group_id` value.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters:
        - name: customer_id
          description: The ID of the customer to remove from the group.
          schema:
            type: string
          in: path
          required: true
        - name: group_id
          description: The ID of the customer group to remove the customer from.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveGroupFromCustomerResponse'
    put:
      tags:
        - Customers
      summary: AddGroupToCustomer
      operationId: AddGroupToCustomer
      description: |-
        Adds a group membership to a customer.

        The customer is identified by the `customer_id` value
        and the customer group is identified by the `group_id` value.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_WRITE
      parameters:
        - name: customer_id
          description: The ID of the customer to add to a group.
          schema:
            type: string
          in: path
          required: true
        - name: group_id
          description: The ID of the customer group to add the customer to.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddGroupToCustomerResponse'
  /v2/devices:
    get:
      tags:
        - Devices
      summary: ListDevices
      operationId: ListDevices
      description: |-
        List devices associated with the merchant. Currently, only Terminal API
        devices are supported.
      x-release-status: BETA
      security:
        - oauth2:
            - DEVICES_READ
      parameters:
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            See
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination)
            for more information.
          schema:
            type: string
          in: query
          required: false
        - name: sort_order
          description: |-
            The order in which results are listed.
            - `ASC` - Oldest to newest.
            - `DESC` - Newest to oldest (default).
          schema:
            $ref: '#/components/schemas/SortOrder'
          in: query
          required: false
        - name: limit
          description: The number of results to return in a single page.
          schema:
            type: integer
          in: query
          required: false
        - name: location_id
          description: If present, only returns devices at the target location.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDevicesResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
  /v2/devices/codes:
    get:
      tags:
        - Devices
      summary: ListDeviceCodes
      operationId: ListDeviceCodes
      description: Lists all DeviceCodes associated with the merchant.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - DEVICE_CREDENTIAL_MANAGEMENT
      parameters:
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for your original
            query.


            See [Paginating
            results](https://developer.squareup.com/docs/working-with-apis/pagination)
            for more information.
          schema:
            type: string
          in: query
          required: false
        - name: location_id
          description: |-
            If specified, only returns DeviceCodes of the specified location.
            Returns DeviceCodes of all locations if empty.
          schema:
            type: string
          in: query
          required: false
        - name: product_type
          description: >-
            If specified, only returns DeviceCodes targeting the specified
            product type.

            Returns DeviceCodes of all product types if empty.
          schema:
            $ref: '#/components/schemas/ProductType'
          in: query
          required: false
        - name: status
          description: |-
            If specified, returns DeviceCodes with the specified statuses.
            Returns DeviceCodes of status `PAIRED` and `UNPAIRED` if empty.
          schema:
            $ref: '#/components/schemas/DeviceCodeStatus'
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDeviceCodesResponse'
      x-endpoint-errors:
        - error-code: INVALID_CURSOR
        - error-code: BAD_REQUEST
    post:
      tags:
        - Devices
      summary: CreateDeviceCode
      operationId: CreateDeviceCode
      description: >-
        Creates a DeviceCode that can be used to login to a Square Terminal
        device to enter the connected

        terminal mode.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - DEVICE_CREDENTIAL_MANAGEMENT
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeviceCodeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDeviceCodeResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: IDEMPOTENCY_KEY_REUSED
        - error-code: INVALID_VALUE
        - error-code: UNAUTHORIZED
  /v2/devices/codes/{id}:
    get:
      tags:
        - Devices
      summary: GetDeviceCode
      operationId: GetDeviceCode
      description: Retrieves DeviceCode with the associated ID.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - DEVICE_CREDENTIAL_MANAGEMENT
      parameters:
        - name: id
          description: The unique identifier for the device code.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDeviceCodeResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: NOT_FOUND
        - error-code: UNAUTHORIZED
  /v2/devices/{device_id}:
    get:
      tags:
        - Devices
      summary: GetDevice
      operationId: GetDevice
      description: Retrieves Device with the associated `device_id`.
      x-release-status: BETA
      security:
        - oauth2:
            - DEVICES_READ
      parameters:
        - name: device_id
          description: The unique ID for the desired `Device`.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDeviceResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: NOT_FOUND
  /v2/disputes:
    get:
      tags:
        - Disputes
      summary: ListDisputes
      operationId: ListDisputes
      description: Returns a list of disputes associated with a particular account.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - DISPUTES_READ
      parameters:
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: states
          description: >-
            The dispute states used to filter the result. If not specified, the
            endpoint returns all disputes.
          schema:
            $ref: '#/components/schemas/DisputeState'
          in: query
          required: false
        - name: location_id
          description: >-
            The ID of the location for which to return a list of disputes.

            If not specified, the endpoint returns disputes associated with all
            locations.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDisputesResponse'
  /v2/disputes/{dispute_id}:
    get:
      tags:
        - Disputes
      summary: RetrieveDispute
      operationId: RetrieveDispute
      description: Returns details about a specific dispute.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - DISPUTES_READ
      parameters:
        - name: dispute_id
          description: The ID of the dispute you want more details about.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveDisputeResponse'
  /v2/disputes/{dispute_id}/accept:
    post:
      tags:
        - Disputes
      summary: AcceptDispute
      operationId: AcceptDispute
      description: >-
        Accepts the loss on a dispute. Square returns the disputed amount to the
        cardholder and

        updates the dispute state to ACCEPTED.


        Square debits the disputed amount from the sellers Square account. If
        the Square account

        does not have sufficient funds, Square debits the associated bank
        account.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - DISPUTES_WRITE
      parameters:
        - name: dispute_id
          description: The ID of the dispute you want to accept.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptDisputeResponse'
  /v2/disputes/{dispute_id}/evidence:
    get:
      tags:
        - Disputes
      summary: ListDisputeEvidence
      operationId: ListDisputeEvidence
      description: Returns a list of evidence associated with a dispute.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - DISPUTES_READ
      parameters:
        - name: dispute_id
          description: The ID of the dispute.
          schema:
            type: string
          in: path
          required: true
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDisputeEvidenceResponse'
  /v2/disputes/{dispute_id}/evidence-files:
    post:
      tags:
        - Disputes
      summary: CreateDisputeEvidenceFile
      operationId: CreateDisputeEvidenceFile
      description: >-
        Uploads a file to use as evidence in a dispute challenge. The endpoint
        accepts HTTP

        multipart/form-data file uploads in HEIC, HEIF, JPEG, PDF, PNG, and TIFF
        formats.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - DISPUTES_WRITE
      parameters:
        - name: dispute_id
          description: The ID of the dispute for which you want to upload evidence.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                request:
                  $ref: '#/components/schemas/CreateDisputeEvidenceFileRequest'
                image_file:
                  type: string
                  format: binary
            encoding:
              image_file:
                contentType: image/jpeg
              request:
                contentType: application/json; charset=utf-8
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDisputeEvidenceFileResponse'
  /v2/disputes/{dispute_id}/evidence-text:
    post:
      tags:
        - Disputes
      summary: CreateDisputeEvidenceText
      operationId: CreateDisputeEvidenceText
      description: Uploads text to use as evidence for a dispute challenge.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - DISPUTES_WRITE
      parameters:
        - name: dispute_id
          description: The ID of the dispute for which you want to upload evidence.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDisputeEvidenceTextRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDisputeEvidenceTextResponse'
  /v2/disputes/{dispute_id}/evidence/{evidence_id}:
    delete:
      tags:
        - Disputes
      summary: DeleteDisputeEvidence
      operationId: DeleteDisputeEvidence
      description: |-
        Removes specified evidence from a dispute.
        Square does not send the bank any evidence that is removed.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - DISPUTES_WRITE
      parameters:
        - name: dispute_id
          description: The ID of the dispute from which you want to remove evidence.
          schema:
            type: string
          in: path
          required: true
        - name: evidence_id
          description: The ID of the evidence you want to remove.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDisputeEvidenceResponse'
    get:
      tags:
        - Disputes
      summary: RetrieveDisputeEvidence
      operationId: RetrieveDisputeEvidence
      description: >-
        Returns the metadata for the evidence specified in the request URL path.


        You must maintain a copy of any evidence uploaded if you want to
        reference it later. Evidence cannot be downloaded after you upload it.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - DISPUTES_READ
      parameters:
        - name: dispute_id
          description: >-
            The ID of the dispute from which you want to retrieve evidence
            metadata.
          schema:
            type: string
          in: path
          required: true
        - name: evidence_id
          description: The ID of the evidence to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveDisputeEvidenceResponse'
  /v2/disputes/{dispute_id}/submit-evidence:
    post:
      tags:
        - Disputes
      summary: SubmitEvidence
      operationId: SubmitEvidence
      description: >-
        Submits evidence to the cardholder's bank.


        The evidence submitted by this endpoint includes evidence uploaded

        using the
        [CreateDisputeEvidenceFile](api-endpoint:Disputes-CreateDisputeEvidenceFile)
        and

        [CreateDisputeEvidenceText](api-endpoint:Disputes-CreateDisputeEvidenceText)
        endpoints and

        evidence automatically provided by Square, when available. Evidence
        cannot be removed from

        a dispute after submission.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - DISPUTES_WRITE
      parameters:
        - name: dispute_id
          description: The ID of the dispute for which you want to submit evidence.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitEvidenceResponse'
  /v2/employees:
    get:
      tags:
        - Employees
      summary: ListEmployees
      operationId: ListEmployees
      description: ''
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2020-08-26'
        retirementDate: '2021-08-26'
        replacedBy: SearchTeamMembers
        guideUrl: https://developer.squareup.com/docs/team/migrate-from-v2-employees
      security:
        - oauth2:
            - EMPLOYEES_READ
      parameters:
        - name: location_id
          description: ''
          schema:
            type: string
          in: query
          required: false
        - name: status
          description: Specifies the EmployeeStatus to filter the employee by.
          schema:
            $ref: '#/components/schemas/EmployeeStatus'
          in: query
          required: false
        - name: limit
          description: The number of employees to be returned on each page.
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: The token required to retrieve the specified page of results.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEmployeesResponse'
  /v2/employees/{id}:
    get:
      tags:
        - Employees
      summary: RetrieveEmployee
      operationId: RetrieveEmployee
      description: ''
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2020-08-26'
        retirementDate: '2021-08-26'
        replacedBy: RetrieveTeamMember
        guideUrl: https://developer.squareup.com/docs/team/migrate-from-v2-employees
      security:
        - oauth2:
            - EMPLOYEES_READ
      parameters:
        - name: id
          description: UUID for the employee that was requested.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveEmployeeResponse'
  /v2/events:
    post:
      tags:
        - Events
      summary: SearchEvents
      operationId: SearchEvents
      description: Search for Square API events that occur within a 28-day timeframe.
      x-release-status: BETA
      security:
        - oauth2: []
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchEventsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchEventsResponse'
  /v2/events/disable:
    put:
      tags:
        - Events
      summary: DisableEvents
      operationId: DisableEvents
      description: >-
        Disables events to prevent them from being searchable.

        All events are disabled by default. You must enable events to make them
        searchable.

        Disabling events for a specific time period prevents them from being
        searchable, even if you re-enable them later.
      x-release-status: BETA
      security:
        - oauth2: []
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DisableEventsResponse'
  /v2/events/enable:
    put:
      tags:
        - Events
      summary: EnableEvents
      operationId: EnableEvents
      description: >-
        Enables events to make them searchable. Only events that occur while in
        the enabled state are searchable.
      x-release-status: BETA
      security:
        - oauth2: []
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnableEventsResponse'
  /v2/events/types:
    get:
      tags:
        - Events
      summary: ListEventTypes
      operationId: ListEventTypes
      description: >-
        Lists all event types that you can subscribe to as webhooks or query
        using the Events API.
      x-release-status: BETA
      security:
        - oauth2: []
      parameters:
        - name: api_version
          description: >-
            The API version for which to list event types. Setting this field
            overrides the default version used by the application.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEventTypesResponse'
  /v2/gift-cards:
    get:
      tags:
        - GiftCards
      summary: ListGiftCards
      operationId: ListGiftCards
      description: >-
        Lists all gift cards. You can specify optional filters to retrieve 

        a subset of the gift cards. Results are sorted by `created_at` in
        ascending order.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - GIFTCARDS_READ
      parameters:
        - name: type
          description: >-
            If a [type](entity:GiftCardType) is provided, the endpoint returns
            gift cards of the specified type.

            Otherwise, the endpoint returns gift cards of all types.
          schema:
            type: string
          in: query
          required: false
        - name: state
          description: >-
            If a [state](entity:GiftCardStatus) is provided, the endpoint
            returns the gift cards in the specified state.

            Otherwise, the endpoint returns the gift cards of all states.
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            If a limit is provided, the endpoint returns only the specified
            number of results per page.

            The maximum value is 200. The default value is 30.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            If a cursor is not provided, the endpoint returns the first page of
            the results. 

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: customer_id
          description: >-
            If a customer ID is provided, the endpoint returns only the gift
            cards linked to the specified customer.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGiftCardsResponse'
    post:
      tags:
        - GiftCards
      summary: CreateGiftCard
      operationId: CreateGiftCard
      description: >-
        Creates a digital gift card or registers a physical (plastic) gift card.
        The resulting gift card

        has a `PENDING` state. To activate a gift card so that it can be
        redeemed for purchases, call

        [CreateGiftCardActivity](api-endpoint:GiftCardActivities-CreateGiftCardActivity)
        and create an `ACTIVATE`

        activity with the initial balance. Alternatively, you can use
        [RefundPayment](api-endpoint:Refunds-RefundPayment)

        to refund a payment to the new gift card.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - GIFTCARDS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGiftCardRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateGiftCardResponse'
      x-endpoint-errors:
        - error-code: TEMPORARY_ERROR
  /v2/gift-cards/activities:
    get:
      tags:
        - GiftCardActivities
      summary: ListGiftCardActivities
      operationId: ListGiftCardActivities
      description: >-
        Lists gift card activities. By default, you get gift card activities for
        all

        gift cards in the seller's account. You can optionally specify query
        parameters to

        filter the list. For example, you can get a list of gift card activities
        for a gift card,

        for all gift cards in a specific region, or for activities within a time
        window.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - GIFTCARDS_READ
      parameters:
        - name: gift_card_id
          description: >-
            If a gift card ID is provided, the endpoint returns activities
            related 

            to the specified gift card. Otherwise, the endpoint returns all gift
            card activities for 

            the seller.
          schema:
            type: string
          in: query
          required: false
        - name: type
          description: >-
            If a [type](entity:GiftCardActivityType) is provided, the endpoint
            returns gift card activities of the specified type. 

            Otherwise, the endpoint returns all types of gift card activities.
          schema:
            type: string
          in: query
          required: false
        - name: location_id
          description: >-
            If a location ID is provided, the endpoint returns gift card
            activities for the specified location. 

            Otherwise, the endpoint returns gift card activities for all
            locations.
          schema:
            type: string
          in: query
          required: false
        - name: begin_time
          description: >-
            The timestamp for the beginning of the reporting period, in RFC 3339
            format.

            This start time is inclusive. The default value is the current time
            minus one year.
          schema:
            type: string
          in: query
          required: false
        - name: end_time
          description: >-
            The timestamp for the end of the reporting period, in RFC 3339
            format.

            This end time is inclusive. The default value is the current time.
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            If a limit is provided, the endpoint returns the specified number 

            of results (or fewer) per page. The maximum value is 100. The
            default value is 50.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            If a cursor is not provided, the endpoint returns the first page of
            the results.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: sort_order
          description: >-
            The order in which the endpoint returns the activities, based on
            `created_at`.

            - `ASC` - Oldest to newest.

            - `DESC` - Newest to oldest (default).
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGiftCardActivitiesResponse'
    post:
      tags:
        - GiftCardActivities
      summary: CreateGiftCardActivity
      operationId: CreateGiftCardActivity
      description: >-
        Creates a gift card activity to manage the balance or state of a [gift
        card](entity:GiftCard).

        For example, create an `ACTIVATE` activity to activate a gift card with
        an initial balance before first use.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - GIFTCARDS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGiftCardActivityRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateGiftCardActivityResponse'
      x-endpoint-errors:
        - error-code: INSUFFICIENT_FUNDS
        - error-code: PAYMENT_LIMIT_EXCEEDED
        - error-code: REFUND_AMOUNT_INVALID
        - error-code: TEMPORARY_ERROR
  /v2/gift-cards/from-gan:
    post:
      tags:
        - GiftCards
      summary: RetrieveGiftCardFromGAN
      operationId: RetrieveGiftCardFromGAN
      description: Retrieves a gift card using the gift card account number (GAN).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - GIFTCARDS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveGiftCardFromGANRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveGiftCardFromGANResponse'
  /v2/gift-cards/from-nonce:
    post:
      tags:
        - GiftCards
      summary: RetrieveGiftCardFromNonce
      operationId: RetrieveGiftCardFromNonce
      description: >-
        Retrieves a gift card using a secure payment token that represents the
        gift card.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - GIFTCARDS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveGiftCardFromNonceRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveGiftCardFromNonceResponse'
      x-endpoint-errors:
        - error-code: CARD_TOKEN_EXPIRED
        - error-code: CARD_TOKEN_USED
  /v2/gift-cards/{gift_card_id}/link-customer:
    post:
      tags:
        - GiftCards
      summary: LinkCustomerToGiftCard
      operationId: LinkCustomerToGiftCard
      description: >-
        Links a customer to a gift card, which is also referred to as adding a
        card on file.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - GIFTCARDS_WRITE
      parameters:
        - name: gift_card_id
          description: The ID of the gift card to be linked.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkCustomerToGiftCardRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LinkCustomerToGiftCardResponse'
  /v2/gift-cards/{gift_card_id}/unlink-customer:
    post:
      tags:
        - GiftCards
      summary: UnlinkCustomerFromGiftCard
      operationId: UnlinkCustomerFromGiftCard
      description: >-
        Unlinks a customer from a gift card, which is also referred to as
        removing a card on file.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - GIFTCARDS_WRITE
      parameters:
        - name: gift_card_id
          description: The ID of the gift card to be unlinked.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnlinkCustomerFromGiftCardRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnlinkCustomerFromGiftCardResponse'
  /v2/gift-cards/{id}:
    get:
      tags:
        - GiftCards
      summary: RetrieveGiftCard
      operationId: RetrieveGiftCard
      description: Retrieves a gift card using the gift card ID.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - GIFTCARDS_READ
      parameters:
        - name: id
          description: The ID of the gift card to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveGiftCardResponse'
  /v2/inventory/adjustment/{adjustment_id}:
    get:
      tags:
        - Inventory
      summary: DeprecatedRetrieveInventoryAdjustment
      operationId: DeprecatedRetrieveInventoryAdjustment
      description: >-
        Deprecated version of
        [RetrieveInventoryAdjustment](api-endpoint:Inventory-RetrieveInventoryAdjustment)
        after the endpoint URL

        is updated to conform to the standard convention.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2021-06-16'
        retirementDate: '2023-11-15'
        replacedBy: RetrieveInventoryAdjustment
      security:
        - oauth2:
            - INVENTORY_READ
      parameters:
        - name: adjustment_id
          description: >-
            ID of the [InventoryAdjustment](entity:InventoryAdjustment) to
            retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveInventoryAdjustmentResponse'
  /v2/inventory/adjustments/{adjustment_id}:
    get:
      tags:
        - Inventory
      summary: RetrieveInventoryAdjustment
      operationId: RetrieveInventoryAdjustment
      description: |-
        Returns the [InventoryAdjustment](entity:InventoryAdjustment) object
        with the provided `adjustment_id`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - INVENTORY_READ
      parameters:
        - name: adjustment_id
          description: >-
            ID of the [InventoryAdjustment](entity:InventoryAdjustment) to
            retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveInventoryAdjustmentResponse'
  /v2/inventory/batch-change:
    post:
      tags:
        - Inventory
      summary: DeprecatedBatchChangeInventory
      operationId: DeprecatedBatchChangeInventory
      description: >-
        Deprecated version of
        [BatchChangeInventory](api-endpoint:Inventory-BatchChangeInventory)
        after the endpoint URL

        is updated to conform to the standard convention.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2021-06-16'
        retirementDate: '2023-11-15'
        replacedBy: BatchChangeInventory
      security:
        - oauth2:
            - INVENTORY_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchChangeInventoryRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchChangeInventoryResponse'
  /v2/inventory/batch-retrieve-changes:
    post:
      tags:
        - Inventory
      summary: DeprecatedBatchRetrieveInventoryChanges
      operationId: DeprecatedBatchRetrieveInventoryChanges
      description: >-
        Deprecated version of
        [BatchRetrieveInventoryChanges](api-endpoint:Inventory-BatchRetrieveInventoryChanges)
        after the endpoint URL

        is updated to conform to the standard convention.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2021-06-16'
        retirementDate: '2023-11-15'
        replacedBy: BatchRetrieveInventoryChanges
      security:
        - oauth2:
            - INVENTORY_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRetrieveInventoryChangesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchRetrieveInventoryChangesResponse'
  /v2/inventory/batch-retrieve-counts:
    post:
      tags:
        - Inventory
      summary: DeprecatedBatchRetrieveInventoryCounts
      operationId: DeprecatedBatchRetrieveInventoryCounts
      description: >-
        Deprecated version of
        [BatchRetrieveInventoryCounts](api-endpoint:Inventory-BatchRetrieveInventoryCounts)
        after the endpoint URL

        is updated to conform to the standard convention.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2021-06-16'
        retirementDate: '2023-11-15'
        replacedBy: BatchRetrieveInventoryCounts
      security:
        - oauth2:
            - INVENTORY_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRetrieveInventoryCountsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchRetrieveInventoryCountsResponse'
  /v2/inventory/changes/batch-create:
    post:
      tags:
        - Inventory
      summary: BatchChangeInventory
      operationId: BatchChangeInventory
      description: |-
        Applies adjustments and counts to the provided item quantities.

        On success: returns the current calculated counts for all objects
        referenced in the request.
        On failure: returns a list of related errors.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - INVENTORY_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchChangeInventoryRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchChangeInventoryResponse'
  /v2/inventory/changes/batch-retrieve:
    post:
      tags:
        - Inventory
      summary: BatchRetrieveInventoryChanges
      operationId: BatchRetrieveInventoryChanges
      description: |-
        Returns historical physical counts and adjustments based on the
        provided filter criteria.

        Results are paginated and sorted in ascending order according their
        `occurred_at` timestamp (oldest first).

        BatchRetrieveInventoryChanges is a catch-all query endpoint for queries
        that cannot be handled by other, simpler endpoints.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - INVENTORY_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRetrieveInventoryChangesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchRetrieveInventoryChangesResponse'
  /v2/inventory/counts/batch-retrieve:
    post:
      tags:
        - Inventory
      summary: BatchRetrieveInventoryCounts
      operationId: BatchRetrieveInventoryCounts
      description: >-
        Returns current counts for the provided

        [CatalogObject](entity:CatalogObject)s at the requested

        [Location](entity:Location)s.


        Results are paginated and sorted in descending order according to their

        `calculated_at` timestamp (newest first).


        When `updated_after` is specified, only counts that have changed since
        that

        time (based on the server timestamp for the most recent change) are

        returned. This allows clients to perform a "sync" operation, for example

        in response to receiving a Webhook notification.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - INVENTORY_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRetrieveInventoryCountsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchRetrieveInventoryCountsResponse'
  /v2/inventory/physical-count/{physical_count_id}:
    get:
      tags:
        - Inventory
      summary: DeprecatedRetrieveInventoryPhysicalCount
      operationId: DeprecatedRetrieveInventoryPhysicalCount
      description: >-
        Deprecated version of
        [RetrieveInventoryPhysicalCount](api-endpoint:Inventory-RetrieveInventoryPhysicalCount)
        after the endpoint URL

        is updated to conform to the standard convention.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2021-06-16'
        retirementDate: '2023-11-15'
        replacedBy: RetrieveInventoryPhysicalCount
      security:
        - oauth2:
            - INVENTORY_READ
      parameters:
        - name: physical_count_id
          description: |-
            ID of the
            [InventoryPhysicalCount](entity:InventoryPhysicalCount) to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveInventoryPhysicalCountResponse'
  /v2/inventory/physical-counts/{physical_count_id}:
    get:
      tags:
        - Inventory
      summary: RetrieveInventoryPhysicalCount
      operationId: RetrieveInventoryPhysicalCount
      description: |-
        Returns the [InventoryPhysicalCount](entity:InventoryPhysicalCount)
        object with the provided `physical_count_id`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - INVENTORY_READ
      parameters:
        - name: physical_count_id
          description: |-
            ID of the
            [InventoryPhysicalCount](entity:InventoryPhysicalCount) to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveInventoryPhysicalCountResponse'
  /v2/inventory/transfers/{transfer_id}:
    get:
      tags:
        - Inventory
      summary: RetrieveInventoryTransfer
      operationId: RetrieveInventoryTransfer
      description: |-
        Returns the [InventoryTransfer](entity:InventoryTransfer) object
        with the provided `transfer_id`.
      x-release-status: BETA
      security:
        - oauth2:
            - INVENTORY_READ
      parameters:
        - name: transfer_id
          description: ID of the [InventoryTransfer](entity:InventoryTransfer) to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveInventoryTransferResponse'
  /v2/inventory/{catalog_object_id}:
    get:
      tags:
        - Inventory
      summary: RetrieveInventoryCount
      operationId: RetrieveInventoryCount
      description: |-
        Retrieves the current calculated stock count for a given
        [CatalogObject](entity:CatalogObject) at a given set of
        [Location](entity:Location)s. Responses are paginated and unsorted.
        For more sophisticated queries, use a batch endpoint.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - INVENTORY_READ
      parameters:
        - name: catalog_object_id
          description: ID of the [CatalogObject](entity:CatalogObject) to retrieve.
          schema:
            type: string
          in: path
          required: true
        - name: location_ids
          description: |-
            The [Location](entity:Location) IDs to look up as a comma-separated
            list. An empty list queries all locations.
          schema:
            type: string
          in: query
          required: false
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for the original
            query.


            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveInventoryCountResponse'
  /v2/inventory/{catalog_object_id}/changes:
    get:
      tags:
        - Inventory
      summary: RetrieveInventoryChanges
      operationId: RetrieveInventoryChanges
      description: >-
        Returns a set of physical counts and inventory adjustments for the

        provided [CatalogObject](entity:CatalogObject) at the requested

        [Location](entity:Location)s.


        You can achieve the same result by calling
        [BatchRetrieveInventoryChanges](api-endpoint:Inventory-BatchRetrieveInventoryChanges)

        and having the `catalog_object_ids` list contain a single element of the
        `CatalogObject` ID.


        Results are paginated and sorted in descending order according to their

        `occurred_at` timestamp (newest first).


        There are no limits on how far back the caller can page. This endpoint
        can be

        used to display recent changes for a specific item. For more

        sophisticated queries, use a batch endpoint.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2021-06-16'
        retirementDate: '2023-11-15'
        replacedBy: BatchRetrieveInventoryChanges
      security:
        - oauth2:
            - INVENTORY_READ
      parameters:
        - name: catalog_object_id
          description: ID of the [CatalogObject](entity:CatalogObject) to retrieve.
          schema:
            type: string
          in: path
          required: true
        - name: location_ids
          description: |-
            The [Location](entity:Location) IDs to look up as a comma-separated
            list. An empty list queries all locations.
          schema:
            type: string
          in: query
          required: false
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for the original
            query.


            See the
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination)
            guide for more information.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveInventoryChangesResponse'
  /v2/invoices:
    get:
      tags:
        - Invoices
      summary: ListInvoices
      operationId: ListInvoices
      description: >-
        Returns a list of invoices for a given location. The response 

        is paginated. If truncated, the response includes a `cursor` that
        you    

        use in a subsequent request to retrieve the next set of invoices.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - INVOICES_READ
      parameters:
        - name: location_id
          description: The ID of the location for which to list invoices.
          schema:
            type: string
          in: query
          required: true
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint. 

            Provide this cursor to retrieve the next set of results for your
            original query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of invoices to return (200 is the maximum
            `limit`). 

            If not provided, the server uses a default limit of 100 invoices.
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListInvoicesResponse'
    post:
      tags:
        - Invoices
      summary: CreateInvoice
      operationId: CreateInvoice
      description: >-
        Creates a draft [invoice](entity:Invoice) 

        for an order created using the Orders API.


        A draft invoice remains in your account and no action is taken. 

        You must publish the invoice before Square can process it (send it to
        the customer's email address or charge the customers card on file).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ORDERS_WRITE
            - INVOICES_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvoiceRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInvoiceResponse'
      x-endpoint-errors:
        - error-code: INVALID_CARD
        - error-code: MERCHANT_SUBSCRIPTION_NOT_FOUND
  /v2/invoices/search:
    post:
      tags:
        - Invoices
      summary: SearchInvoices
      operationId: SearchInvoices
      description: >-
        Searches for invoices from a location specified in 

        the filter. You can optionally specify customers in the filter for whom
        to 

        retrieve invoices. In the current implementation, you can only specify
        one location and 

        optionally one customer.


        The response is paginated. If truncated, the response includes a
        `cursor` 

        that you use in a subsequent request to retrieve the next set of
        invoices.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - INVOICES_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchInvoicesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchInvoicesResponse'
  /v2/invoices/{invoice_id}:
    delete:
      tags:
        - Invoices
      summary: DeleteInvoice
      operationId: DeleteInvoice
      description: >-
        Deletes the specified invoice. When an invoice is deleted, the 

        associated order status changes to CANCELED. You can only delete a
        draft 

        invoice (you cannot delete a published invoice, including one that is
        scheduled for processing).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ORDERS_WRITE
            - INVOICES_WRITE
      parameters:
        - name: invoice_id
          description: The ID of the invoice to delete.
          schema:
            type: string
          in: path
          required: true
        - name: version
          description: >-
            The version of the [invoice](entity:Invoice) to delete.

            If you do not know the version, you can call
            [GetInvoice](api-endpoint:Invoices-GetInvoice) or 

            [ListInvoices](api-endpoint:Invoices-ListInvoices).
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteInvoiceResponse'
    get:
      tags:
        - Invoices
      summary: GetInvoice
      operationId: GetInvoice
      description: Retrieves an invoice by invoice ID.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - INVOICES_READ
      parameters:
        - name: invoice_id
          description: The ID of the invoice to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInvoiceResponse'
    put:
      tags:
        - Invoices
      summary: UpdateInvoice
      operationId: UpdateInvoice
      description: >-
        Updates an invoice. This endpoint supports sparse updates, so you only
        need

        to specify the fields you want to change along with the required
        `version` field.

        Some restrictions apply to updating invoices. For example, you cannot
        change the

        `order_id` or `location_id` field.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ORDERS_WRITE
            - INVOICES_WRITE
      parameters:
        - name: invoice_id
          description: The ID of the invoice to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInvoiceRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateInvoiceResponse'
      x-endpoint-errors:
        - error-code: CARD_DECLINED
        - error-code: INVALID_CARD
        - error-code: MERCHANT_SUBSCRIPTION_NOT_FOUND
  /v2/invoices/{invoice_id}/attachments:
    post:
      tags:
        - Invoices
      summary: CreateInvoiceAttachment
      operationId: CreateInvoiceAttachment
      description: >-
        Uploads a file and attaches it to an invoice. This endpoint accepts HTTP
        multipart/form-data file uploads

        with a JSON `request` part and a `file` part. The `file` part must be a
        `readable stream` that contains a file

        in a supported format: GIF, JPEG, PNG, TIFF, BMP, or PDF.


        Invoices can have up to 10 attachments with a total file size of 25 MB.
        Attachments can be added only to invoices

        in the `DRAFT`, `SCHEDULED`, `UNPAID`, or `PARTIALLY_PAID` state.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - INVOICES_WRITE
      parameters:
        - name: invoice_id
          description: The ID of the [invoice](entity:Invoice) to attach the file to.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                request:
                  $ref: '#/components/schemas/CreateInvoiceAttachmentRequest'
                image_file:
                  type: string
                  format: binary
            encoding:
              image_file:
                contentType: image/jpeg
              request:
                contentType: application/json; charset=utf-8
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateInvoiceAttachmentResponse'
  /v2/invoices/{invoice_id}/attachments/{attachment_id}:
    delete:
      tags:
        - Invoices
      summary: DeleteInvoiceAttachment
      operationId: DeleteInvoiceAttachment
      description: >-
        Removes an attachment from an invoice and permanently deletes the file.
        Attachments can be removed only

        from invoices in the `DRAFT`, `SCHEDULED`, `UNPAID`, or `PARTIALLY_PAID`
        state.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - INVOICES_WRITE
      parameters:
        - name: invoice_id
          description: >-
            The ID of the [invoice](entity:Invoice) to delete the attachment
            from.
          schema:
            type: string
          in: path
          required: true
        - name: attachment_id
          description: The ID of the [attachment](entity:InvoiceAttachment) to delete.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteInvoiceAttachmentResponse'
  /v2/invoices/{invoice_id}/cancel:
    post:
      tags:
        - Invoices
      summary: CancelInvoice
      operationId: CancelInvoice
      description: >-
        Cancels an invoice. The seller cannot collect payments for 

        the canceled invoice.


        You cannot cancel an invoice in the `DRAFT` state or in a terminal
        state: `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ORDERS_WRITE
            - INVOICES_WRITE
      parameters:
        - name: invoice_id
          description: The ID of the [invoice](entity:Invoice) to cancel.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelInvoiceRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelInvoiceResponse'
      x-endpoint-errors:
        - error-code: VERSION_MISMATCH
  /v2/invoices/{invoice_id}/publish:
    post:
      tags:
        - Invoices
      summary: PublishInvoice
      operationId: PublishInvoice
      description: >-
        Publishes the specified draft invoice. 


        After an invoice is published, Square 

        follows up based on the invoice configuration. For example, Square 

        sends the invoice to the customer's email address, charges the
        customer's card on file, or does 

        nothing. Square also makes the invoice available on a Square-hosted
        invoice page. 


        The invoice `status` also changes from `DRAFT` to a status 

        based on the invoice configuration. For example, the status changes to
        `UNPAID` if 

        Square emails the invoice or `PARTIALLY_PAID` if Square charges a card
        on file for a portion of the 

        invoice amount.


        In addition to the required `ORDERS_WRITE` and `INVOICES_WRITE`
        permissions, `CUSTOMERS_READ`

        and `PAYMENTS_WRITE` are required when publishing invoices configured
        for card-on-file payments.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ORDERS_WRITE
            - INVOICES_WRITE
      parameters:
        - name: invoice_id
          description: The ID of the invoice to publish.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishInvoiceRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishInvoiceResponse'
      x-endpoint-errors:
        - error-code: CARD_DECLINED
        - error-code: INVALID_CARD
  /v2/labor/break-types:
    get:
      tags:
        - Labor
      summary: ListBreakTypes
      operationId: ListBreakTypes
      description: Returns a paginated list of `BreakType` instances for a business.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - TIMECARDS_SETTINGS_READ
      parameters:
        - name: location_id
          description: >-
            Filter the returned `BreakType` results to only those that are
            associated with the

            specified location.
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of `BreakType` results to return per page. The
            number can range between 1

            and 200. The default is 200.
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: A pointer to the next page of `BreakType` results to fetch.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBreakTypesResponse'
    post:
      tags:
        - Labor
      summary: CreateBreakType
      operationId: CreateBreakType
      description: >-
        Creates a new `BreakType`.


        A `BreakType` is a template for creating `Break` objects.

        You must provide the following values in your request to this

        endpoint:


        - `location_id`

        - `break_name`

        - `expected_duration`

        - `is_paid`


        You can only have three `BreakType` instances per location. If you
        attempt to add a fourth

        `BreakType` for a location, an `INVALID_REQUEST_ERROR` "Exceeded limit
        of 3 breaks per location."

        is returned.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - TIMECARDS_SETTINGS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBreakTypeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateBreakTypeResponse'
  /v2/labor/break-types/{id}:
    delete:
      tags:
        - Labor
      summary: DeleteBreakType
      operationId: DeleteBreakType
      description: |-
        Deletes an existing `BreakType`.

        A `BreakType` can be deleted even if it is referenced from a `Shift`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - TIMECARDS_SETTINGS_WRITE
      parameters:
        - name: id
          description: The UUID for the `BreakType` being deleted.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteBreakTypeResponse'
    get:
      tags:
        - Labor
      summary: GetBreakType
      operationId: GetBreakType
      description: Returns a single `BreakType` specified by `id`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - TIMECARDS_SETTINGS_READ
      parameters:
        - name: id
          description: The UUID for the `BreakType` being retrieved.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBreakTypeResponse'
    put:
      tags:
        - Labor
      summary: UpdateBreakType
      operationId: UpdateBreakType
      description: Updates an existing `BreakType`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - TIMECARDS_SETTINGS_WRITE
            - TIMECARDS_SETTINGS_READ
      parameters:
        - name: id
          description: ' The UUID for the `BreakType` being updated.'
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateBreakTypeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateBreakTypeResponse'
  /v2/labor/employee-wages:
    get:
      tags:
        - Labor
      summary: ListEmployeeWages
      operationId: ListEmployeeWages
      description: Returns a paginated list of `EmployeeWage` instances for a business.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2020-08-26'
        retirementDate: TBD
        replacedBy: ListTeamMemberWages
        guideUrl: https://developer.squareup.com/docs/labor-api/migrate-to-teams
      security:
        - oauth2:
            - EMPLOYEES_READ
      parameters:
        - name: employee_id
          description: >-
            Filter the returned wages to only those that are associated with the
            specified employee.
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of `EmployeeWage` results to return per page. The
            number can range between

            1 and 200. The default is 200.
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: A pointer to the next page of `EmployeeWage` results to fetch.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEmployeeWagesResponse'
  /v2/labor/employee-wages/{id}:
    get:
      tags:
        - Labor
      summary: GetEmployeeWage
      operationId: GetEmployeeWage
      description: Returns a single `EmployeeWage` specified by `id`.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2020-08-26'
        retirementDate: TBD
        replacedBy: GetTeamMemberWage
        guideUrl: https://developer.squareup.com/docs/labor-api/migrate-to-teams
      security:
        - oauth2:
            - EMPLOYEES_READ
      parameters:
        - name: id
          description: The UUID for the `EmployeeWage` being retrieved.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetEmployeeWageResponse'
  /v2/labor/shifts:
    post:
      tags:
        - Labor
      summary: CreateShift
      operationId: CreateShift
      description: >-
        Creates a new `Shift`.


        A `Shift` represents a complete workday for a single team member.

        You must provide the following values in your request to this

        endpoint:


        - `location_id`

        - `team_member_id`

        - `start_at`


        An attempt to create a new `Shift` can result in a `BAD_REQUEST` error
        when:

        - The `status` of the new `Shift` is `OPEN` and the team member has
        another

        shift with an `OPEN` status.

        - The `start_at` date is in the future.

        - The `start_at` or `end_at` date overlaps another shift for the same
        team member.

        - The `Break` instances are set in the request and a break `start_at`

        is before the `Shift.start_at`, a break `end_at` is after

        the `Shift.end_at`, or both.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - TIMECARDS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateShiftRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateShiftResponse'
  /v2/labor/shifts/search:
    post:
      tags:
        - Labor
      summary: SearchShifts
      operationId: SearchShifts
      description: |-
        Returns a paginated list of `Shift` records for a business.
        The list to be returned can be filtered by:
        - Location IDs
        - Team member IDs
        - Shift status (`OPEN` or `CLOSED`)
        - Shift start
        - Shift end
        - Workday details

        The list can be sorted by:
        - `START_AT`
        - `END_AT`
        - `CREATED_AT`
        - `UPDATED_AT`
      x-release-status: PUBLIC
      security:
        - oauth2:
            - TIMECARDS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchShiftsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchShiftsResponse'
  /v2/labor/shifts/{id}:
    delete:
      tags:
        - Labor
      summary: DeleteShift
      operationId: DeleteShift
      description: Deletes a `Shift`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - TIMECARDS_WRITE
      parameters:
        - name: id
          description: The UUID for the `Shift` being deleted.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteShiftResponse'
    get:
      tags:
        - Labor
      summary: GetShift
      operationId: GetShift
      description: Returns a single `Shift` specified by `id`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - TIMECARDS_READ
      parameters:
        - name: id
          description: The UUID for the `Shift` being retrieved.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetShiftResponse'
    put:
      tags:
        - Labor
      summary: UpdateShift
      operationId: UpdateShift
      description: >-
        Updates an existing `Shift`.


        When adding a `Break` to a `Shift`, any earlier `Break` instances in the
        `Shift` have

        the `end_at` property set to a valid RFC-3339 datetime string.


        When closing a `Shift`, all `Break` instances in the `Shift` must be
        complete with `end_at`

        set on each `Break`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - TIMECARDS_WRITE
            - TIMECARDS_READ
      parameters:
        - name: id
          description: The ID of the object being updated.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateShiftRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateShiftResponse'
  /v2/labor/team-member-wages:
    get:
      tags:
        - Labor
      summary: ListTeamMemberWages
      operationId: ListTeamMemberWages
      description: Returns a paginated list of `TeamMemberWage` instances for a business.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - EMPLOYEES_READ
      parameters:
        - name: team_member_id
          description: |-
            Filter the returned wages to only those that are associated with the
            specified team member.
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of `TeamMemberWage` results to return per page.
            The number can range between

            1 and 200. The default is 200.
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: A pointer to the next page of `EmployeeWage` results to fetch.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTeamMemberWagesResponse'
  /v2/labor/team-member-wages/{id}:
    get:
      tags:
        - Labor
      summary: GetTeamMemberWage
      operationId: GetTeamMemberWage
      description: Returns a single `TeamMemberWage` specified by `id`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - EMPLOYEES_READ
      parameters:
        - name: id
          description: The UUID for the `TeamMemberWage` being retrieved.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTeamMemberWageResponse'
  /v2/labor/workweek-configs:
    get:
      tags:
        - Labor
      summary: ListWorkweekConfigs
      operationId: ListWorkweekConfigs
      description: Returns a list of `WorkweekConfig` instances for a business.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - TIMECARDS_SETTINGS_READ
      parameters:
        - name: limit
          description: The maximum number of `WorkweekConfigs` results to return per page.
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: A pointer to the next page of `WorkweekConfig` results to fetch.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWorkweekConfigsResponse'
  /v2/labor/workweek-configs/{id}:
    put:
      tags:
        - Labor
      summary: UpdateWorkweekConfig
      operationId: UpdateWorkweekConfig
      description: Updates a `WorkweekConfig`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - TIMECARDS_SETTINGS_WRITE
            - TIMECARDS_SETTINGS_READ
      parameters:
        - name: id
          description: The UUID for the `WorkweekConfig` object being updated.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkweekConfigRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateWorkweekConfigResponse'
  /v2/locations:
    get:
      tags:
        - Locations
      summary: ListLocations
      operationId: ListLocations
      description: >-
        Provides details about all of the seller's
        [locations](https://developer.squareup.com/docs/locations-api),

        including those with an inactive status. Locations are listed
        alphabetically by `name`.
      x-release-status: PUBLIC
      x-unitTests:
        - expectedResponse:
            headers: {}
            statusCode: '200'
            x-allowExtraHeaders: true
            x-arrayCheckCount: false
            x-arrayOrderedMatching: false
            x-bodyMatchMode: NONE
            x-matchResponseSchema: true
          request:
            method: GET
            uri: /v2/locations
          x-testEnabled: true
          x-testName: ListLocations
          x-testShouldPass: true
      security:
        - oauth2:
            - MERCHANT_PROFILE_READ
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListLocationsResponse'
    post:
      tags:
        - Locations
      summary: CreateLocation
      operationId: CreateLocation
      description: >-
        Creates a [location](https://developer.squareup.com/docs/locations-api).

        Creating new locations allows for separate configuration of receipt
        layouts, item prices,

        and sales reports. Developers can use locations to separate sales
        activity through applications

        that integrate with Square from sales activity elsewhere in a seller's
        account.

        Locations created programmatically with the Locations API last forever
        and

        are visible to the seller for their own management. Therefore, ensure
        that

        each location has a sensible and unique name.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLocationRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLocationResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
  /v2/locations/custom-attribute-definitions:
    get:
      tags:
        - LocationCustomAttributes
      summary: ListLocationCustomAttributeDefinitions
      operationId: ListLocationCustomAttributeDefinitions
      description: >-
        Lists the location-related [custom attribute
        definitions](entity:CustomAttributeDefinition) that belong to a Square
        seller account.

        When all response pages are retrieved, the results include all custom
        attribute definitions

        that are visible to the requesting application, including those that are
        created by other

        applications and set to `VISIBILITY_READ_ONLY` or
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_READ
      parameters:
        - name: visibility_filter
          description: >-
            Filters the `CustomAttributeDefinition` results by their
            `visibility` values.
          schema:
            $ref: '#/components/schemas/VisibilityFilter'
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ListLocationCustomAttributeDefinitionsResponse
    post:
      tags:
        - LocationCustomAttributes
      summary: CreateLocationCustomAttributeDefinition
      operationId: CreateLocationCustomAttributeDefinition
      description: >-
        Creates a location-related [custom attribute
        definition](entity:CustomAttributeDefinition) for a Square seller
        account.

        Use this endpoint to define a custom attribute that can be associated
        with locations.

        A custom attribute definition specifies the `key`, `visibility`,
        `schema`, and other properties

        for a custom attribute. After the definition is created, you can call

        [UpsertLocationCustomAttribute](api-endpoint:LocationCustomAttributes-UpsertLocationCustomAttribute)
        or

        [BulkUpsertLocationCustomAttributes](api-endpoint:LocationCustomAttributes-BulkUpsertLocationCustomAttributes)

        to set the custom attribute for locations.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/CreateLocationCustomAttributeDefinitionRequest
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/CreateLocationCustomAttributeDefinitionResponse
  /v2/locations/custom-attribute-definitions/{key}:
    delete:
      tags:
        - LocationCustomAttributes
      summary: DeleteLocationCustomAttributeDefinition
      operationId: DeleteLocationCustomAttributeDefinition
      description: >-
        Deletes a location-related [custom attribute
        definition](entity:CustomAttributeDefinition) from a Square seller
        account.

        Deleting a custom attribute definition also deletes the corresponding
        custom attribute from

        all locations.

        Only the definition owner can delete a custom attribute definition.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters:
        - name: key
          description: The key of the custom attribute definition to delete.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/DeleteLocationCustomAttributeDefinitionResponse
    get:
      tags:
        - LocationCustomAttributes
      summary: RetrieveLocationCustomAttributeDefinition
      operationId: RetrieveLocationCustomAttributeDefinition
      description: >-
        Retrieves a location-related [custom attribute
        definition](entity:CustomAttributeDefinition) from a Square seller
        account.

        To retrieve a custom attribute definition created by another
        application, the `visibility`

        setting must be `VISIBILITY_READ_ONLY` or
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_READ
      parameters:
        - name: key
          description: >-
            The key of the custom attribute definition to retrieve. If the
            requesting application

            is not the definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
        - name: version
          description: >-
            The current version of the custom attribute definition, which is
            used for strongly consistent

            reads to guarantee that you receive the most up-to-date data. When
            included in the request,

            Square returns the specified version or a higher version if one
            exists. If the specified version

            is higher than the current version, Square returns a `BAD_REQUEST`
            error.
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/RetrieveLocationCustomAttributeDefinitionResponse
    put:
      tags:
        - LocationCustomAttributes
      summary: UpdateLocationCustomAttributeDefinition
      operationId: UpdateLocationCustomAttributeDefinition
      description: >-
        Updates a location-related [custom attribute
        definition](entity:CustomAttributeDefinition) for a Square seller
        account.

        Use this endpoint to update the following fields: `name`, `description`,
        `visibility`, or the

        `schema` for a `Selection` data type.

        Only the definition owner can update a custom attribute definition.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters:
        - name: key
          description: The key of the custom attribute definition to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/UpdateLocationCustomAttributeDefinitionRequest
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/UpdateLocationCustomAttributeDefinitionResponse
  /v2/locations/custom-attributes/bulk-delete:
    post:
      tags:
        - LocationCustomAttributes
      summary: BulkDeleteLocationCustomAttributes
      operationId: BulkDeleteLocationCustomAttributes
      description: >-
        Deletes [custom attributes](entity:CustomAttribute) for locations as a
        bulk operation.

        To delete a custom attribute owned by another application, the
        `visibility` setting must be

        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteLocationCustomAttributesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/BulkDeleteLocationCustomAttributesResponse
  /v2/locations/custom-attributes/bulk-upsert:
    post:
      tags:
        - LocationCustomAttributes
      summary: BulkUpsertLocationCustomAttributes
      operationId: BulkUpsertLocationCustomAttributes
      description: >-
        Creates or updates [custom attributes](entity:CustomAttribute) for
        locations as a bulk operation.

        Use this endpoint to set the value of one or more custom attributes for
        one or more locations.

        A custom attribute is based on a custom attribute definition in a Square
        seller account, which is

        created using the
        [CreateLocationCustomAttributeDefinition](api-endpoint:LocationCustomAttributes-CreateLocationCustomAttributeDefinition)
        endpoint.

        This `BulkUpsertLocationCustomAttributes` endpoint accepts a map of 1 to
        25 individual upsert

        requests and returns a map of individual upsert responses. Each upsert
        request has a unique ID

        and provides a location ID and custom attribute. Each upsert response is
        returned with the ID

        of the corresponding request.

        To create or update a custom attribute owned by another application, the
        `visibility` setting

        must be `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpsertLocationCustomAttributesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/BulkUpsertLocationCustomAttributesResponse
  /v2/locations/{location_id}:
    get:
      tags:
        - Locations
      summary: RetrieveLocation
      operationId: RetrieveLocation
      description: >-
        Retrieves details of a single location. Specify "main"

        as the location ID to retrieve details of the [main
        location](https://developer.squareup.com/docs/locations-api#about-the-main-location).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - MERCHANT_PROFILE_READ
      parameters:
        - name: location_id
          description: |-
            The ID of the location to retrieve. Specify the string
            "main" to return the main location.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveLocationResponse'
      x-endpoint-errors:
        - error-code: NOT_FOUND
    put:
      tags:
        - Locations
      summary: UpdateLocation
      operationId: UpdateLocation
      description: Updates a [location](https://developer.squareup.com/docs/locations-api).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters:
        - name: location_id
          description: The ID of the location to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLocationRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateLocationResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
  /v2/locations/{location_id}/checkouts:
    post:
      tags:
        - Checkout
      summary: CreateCheckout
      operationId: CreateCheckout
      description: >-
        Links a `checkoutId` to a `checkout_page_url` that customers are

        directed to in order to provide their payment information using a

        payment processing workflow hosted on connect.squareup.com. 



        NOTE: The Checkout API has been updated with new features. 

        For more information, see [Checkout API
        highlights](https://developer.squareup.com/docs/checkout-api#checkout-api-highlights).
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2022-08-17'
        retirementDate: TBD
        replacedBy: CreatePaymentLink
        guideUrl: https://developer.squareup.com/docs/migrate-from-v1/guides/v1-checkout
      security:
        - oauth2:
            - PAYMENTS_WRITE
            - ORDERS_WRITE
      parameters:
        - name: location_id
          description: The ID of the business location to associate the checkout with.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCheckoutRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCheckoutResponse'
      x-endpoint-errors:
        - error-code: AMOUNT_TOO_HIGH
        - error-code: CARD_PROCESSING_NOT_ENABLED
        - error-code: ORDER_EXPIRED
  /v2/locations/{location_id}/custom-attributes:
    get:
      tags:
        - LocationCustomAttributes
      summary: ListLocationCustomAttributes
      operationId: ListLocationCustomAttributes
      description: >-
        Lists the [custom attributes](entity:CustomAttribute) associated with a
        location.

        You can use the `with_definitions` query parameter to also retrieve
        custom attribute definitions

        in the same call.

        When all response pages are retrieved, the results include all custom
        attributes that are

        visible to the requesting application, including those that are owned by
        other applications

        and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_READ
      parameters:
        - name: location_id
          description: The ID of the target [location](entity:Location).
          schema:
            type: string
          in: path
          required: true
        - name: visibility_filter
          description: >-
            Filters the `CustomAttributeDefinition` results by their
            `visibility` values.
          schema:
            $ref: '#/components/schemas/VisibilityFilter'
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request. For more

            information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: with_definitions
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of each

            custom attribute. Set this parameter to `true` to get the name and
            description of each custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          schema:
            type: boolean
            default: false
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListLocationCustomAttributesResponse'
  /v2/locations/{location_id}/custom-attributes/{key}:
    delete:
      tags:
        - LocationCustomAttributes
      summary: DeleteLocationCustomAttribute
      operationId: DeleteLocationCustomAttribute
      description: >-
        Deletes a [custom attribute](entity:CustomAttribute) associated with a
        location.

        To delete a custom attribute owned by another application, the
        `visibility` setting must be

        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters:
        - name: location_id
          description: The ID of the target [location](entity:Location).
          schema:
            type: string
          in: path
          required: true
        - name: key
          description: >-
            The key of the custom attribute to delete. This key must match the
            `key` of a custom

            attribute definition in the Square seller account. If the requesting
            application is not the

            definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteLocationCustomAttributeResponse'
    get:
      tags:
        - LocationCustomAttributes
      summary: RetrieveLocationCustomAttribute
      operationId: RetrieveLocationCustomAttribute
      description: >-
        Retrieves a [custom attribute](entity:CustomAttribute) associated with a
        location.

        You can use the `with_definition` query parameter to also retrieve the
        custom attribute definition

        in the same call.

        To retrieve a custom attribute owned by another application, the
        `visibility` setting must be

        `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_READ
      parameters:
        - name: location_id
          description: The ID of the target [location](entity:Location).
          schema:
            type: string
          in: path
          required: true
        - name: key
          description: >-
            The key of the custom attribute to retrieve. This key must match the
            `key` of a custom

            attribute definition in the Square seller account. If the requesting
            application is not the

            definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
        - name: with_definition
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of

            the custom attribute. Set this parameter to `true` to get the name
            and description of the custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          schema:
            type: boolean
            default: false
          in: query
          required: false
        - name: version
          description: >-
            The current version of the custom attribute, which is used for
            strongly consistent reads to

            guarantee that you receive the most up-to-date data. When included
            in the request, Square

            returns the specified version or a higher version if one exists. If
            the specified version is

            higher than the current version, Square returns a `BAD_REQUEST`
            error.
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveLocationCustomAttributeResponse'
    post:
      tags:
        - LocationCustomAttributes
      summary: UpsertLocationCustomAttribute
      operationId: UpsertLocationCustomAttribute
      description: >-
        Creates or updates a [custom attribute](entity:CustomAttribute) for a
        location.

        Use this endpoint to set the value of a custom attribute for a specified
        location.

        A custom attribute is based on a custom attribute definition in a Square
        seller account, which

        is created using the
        [CreateLocationCustomAttributeDefinition](api-endpoint:LocationCustomAttributes-CreateLocationCustomAttributeDefinition)
        endpoint.

        To create or update a custom attribute owned by another application, the
        `visibility` setting

        must be `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters:
        - name: location_id
          description: The ID of the target [location](entity:Location).
          schema:
            type: string
          in: path
          required: true
        - name: key
          description: >-
            The key of the custom attribute to create or update. This key must
            match the `key` of a

            custom attribute definition in the Square seller account. If the
            requesting application is not

            the definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertLocationCustomAttributeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertLocationCustomAttributeResponse'
  /v2/locations/{location_id}/transactions:
    get:
      tags:
        - Transactions
      summary: ListTransactions
      operationId: ListTransactions
      description: >-
        Lists transactions for a particular location.


        Transactions include payment information from sales and exchanges and
        refund

        information from returns and exchanges.


        Max results per
        [page](https://developer.squareup.com/docs/working-with-apis/pagination):
        50
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2019-08-15'
        retirementDate: TBD
        replacedBy: SearchOrders
        guideUrl: >-
          https://developer.squareup.com/docs/payments-api/migrate-from-transactions-api
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters:
        - name: location_id
          description: The ID of the location to list transactions for.
          schema:
            type: string
          in: path
          required: true
        - name: begin_time
          description: >-
            The beginning of the requested reporting period, in RFC 3339 format.


            See [Date
            ranges](https://developer.squareup.com/docs/build-basics/working-with-dates)
            for details on date inclusivity/exclusivity.


            Default value: The current time minus one year.
          schema:
            type: string
          in: query
          required: false
        - name: end_time
          description: >-
            The end of the requested reporting period, in RFC 3339 format.


            See [Date
            ranges](https://developer.squareup.com/docs/build-basics/working-with-dates)
            for details on date inclusivity/exclusivity.


            Default value: The current time.
          schema:
            type: string
          in: query
          required: false
        - name: sort_order
          description: |-
            The order in which results are listed in the response (`ASC` for
            oldest first, `DESC` for newest first).

            Default value: `DESC`
          schema:
            $ref: '#/components/schemas/SortOrder'
          in: query
          required: false
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for your original
            query.


            See [Paginating
            results](https://developer.squareup.com/docs/working-with-apis/pagination)
            for more information.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTransactionsResponse'
  /v2/locations/{location_id}/transactions/{transaction_id}:
    get:
      tags:
        - Transactions
      summary: RetrieveTransaction
      operationId: RetrieveTransaction
      description: Retrieves details for a single transaction.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2019-08-15'
        retirementDate: TBD
        replacedBy: BatchRetrieveOrders
        guideUrl: >-
          https://developer.squareup.com/docs/payments-api/migrate-from-transactions-api
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters:
        - name: location_id
          description: The ID of the transaction's associated location.
          schema:
            type: string
          in: path
          required: true
        - name: transaction_id
          description: The ID of the transaction to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveTransactionResponse'
  /v2/locations/{location_id}/transactions/{transaction_id}/capture:
    post:
      tags:
        - Transactions
      summary: CaptureTransaction
      operationId: CaptureTransaction
      description: >-
        Captures a transaction that was created with the
        [Charge](api-endpoint:Transactions-Charge)

        endpoint with a `delay_capture` value of `true`.



        See [Delayed capture
        transactions](https://developer.squareup.com/docs/payments/transactions/overview#delayed-capture)

        for more information.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2019-08-15'
        retirementDate: TBD
        replacedBy: CompletePayment
        guideUrl: >-
          https://developer.squareup.com/docs/payments-api/migrate-from-transactions-api
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters:
        - name: location_id
          description: ''
          schema:
            type: string
          in: path
          required: true
        - name: transaction_id
          description: ''
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CaptureTransactionResponse'
      x-endpoint-errors:
        - error-code: DELAYED_TRANSACTION_CANCELED
        - error-code: DELAYED_TRANSACTION_EXPIRED
  /v2/locations/{location_id}/transactions/{transaction_id}/void:
    post:
      tags:
        - Transactions
      summary: VoidTransaction
      operationId: VoidTransaction
      description: >-
        Cancels a transaction that was created with the
        [Charge](api-endpoint:Transactions-Charge)

        endpoint with a `delay_capture` value of `true`.



        See [Delayed capture
        transactions](https://developer.squareup.com/docs/payments/transactions/overview#delayed-capture)

        for more information.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2019-08-15'
        retirementDate: TBD
        replacedBy: CancelPayment
        guideUrl: >-
          https://developer.squareup.com/docs/payments-api/migrate-from-transactions-api
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters:
        - name: location_id
          description: ''
          schema:
            type: string
          in: path
          required: true
        - name: transaction_id
          description: ''
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VoidTransactionResponse'
      x-endpoint-errors:
        - error-code: DELAYED_TRANSACTION_CAPTURED
        - error-code: DELAYED_TRANSACTION_EXPIRED
  /v2/loyalty/accounts:
    post:
      tags:
        - Loyalty
      summary: CreateLoyaltyAccount
      operationId: CreateLoyaltyAccount
      description: >-
        Creates a loyalty account. To create a loyalty account, you must provide
        the `program_id` and a `mapping` with the `phone_number` of the buyer.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLoyaltyAccountRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLoyaltyAccountResponse'
      x-endpoint-errors:
        - error-code: INVALID_PHONE_NUMBER
  /v2/loyalty/accounts/search:
    post:
      tags:
        - Loyalty
      summary: SearchLoyaltyAccounts
      operationId: SearchLoyaltyAccounts
      description: >-
        Searches for loyalty accounts in a loyalty program.


        You can search for a loyalty account using the phone number or customer
        ID associated with the account. To return all loyalty accounts, specify
        an empty `query` object or omit it entirely.


        Search results are sorted by `created_at` in ascending order.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchLoyaltyAccountsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchLoyaltyAccountsResponse'
  /v2/loyalty/accounts/{account_id}:
    get:
      tags:
        - Loyalty
      summary: RetrieveLoyaltyAccount
      operationId: RetrieveLoyaltyAccount
      description: Retrieves a loyalty account.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_READ
      parameters:
        - name: account_id
          description: The ID of the [loyalty account](entity:LoyaltyAccount) to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveLoyaltyAccountResponse'
  /v2/loyalty/accounts/{account_id}/accumulate:
    post:
      tags:
        - Loyalty
      summary: AccumulateLoyaltyPoints
      operationId: AccumulateLoyaltyPoints
      description: >-
        Adds points earned from a purchase to a [loyalty
        account](entity:LoyaltyAccount).


        - If you are using the Orders API to manage orders, provide the
        `order_id`. Square reads the order

        to compute the points earned from both the base loyalty program and an
        associated

        [loyalty promotion](entity:LoyaltyPromotion). For purchases that qualify
        for multiple accrual

        rules, Square computes points based on the accrual rule that grants the
        most points.

        For purchases that qualify for multiple promotions, Square computes
        points based on the most

        recently created promotion. A purchase must first qualify for program
        points to be eligible for promotion points.


        - If you are not using the Orders API to manage orders, provide `points`
        with the number of points to add.

        You must first perform a client-side computation of the points earned
        from the loyalty program and

        loyalty promotion. For spend-based and visit-based programs, you can
        call
        [CalculateLoyaltyPoints](api-endpoint:Loyalty-CalculateLoyaltyPoints)

        to compute the points earned from the base loyalty program. For
        information about computing points earned from a loyalty promotion, see

        [Calculating promotion
        points](https://developer.squareup.com/docs/loyalty-api/loyalty-promotions#calculate-promotion-points).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_WRITE
      parameters:
        - name: account_id
          description: The ID of the target [loyalty account](entity:LoyaltyAccount).
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccumulateLoyaltyPointsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccumulateLoyaltyPointsResponse'
  /v2/loyalty/accounts/{account_id}/adjust:
    post:
      tags:
        - Loyalty
      summary: AdjustLoyaltyPoints
      operationId: AdjustLoyaltyPoints
      description: >-
        Adds points to or subtracts points from a buyer's account.


        Use this endpoint only when you need to manually adjust points.
        Otherwise, in your application flow, you call

        [AccumulateLoyaltyPoints](api-endpoint:Loyalty-AccumulateLoyaltyPoints)

        to add points when a buyer pays for the purchase.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_WRITE
      parameters:
        - name: account_id
          description: The ID of the target [loyalty account](entity:LoyaltyAccount).
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdjustLoyaltyPointsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdjustLoyaltyPointsResponse'
  /v2/loyalty/events/search:
    post:
      tags:
        - Loyalty
      summary: SearchLoyaltyEvents
      operationId: SearchLoyaltyEvents
      description: >-
        Searches for loyalty events.


        A Square loyalty program maintains a ledger of events that occur during
        the lifetime of a

        buyer's loyalty account. Each change in the point balance

        (for example, points earned, points redeemed, and points expired) is

        recorded in the ledger. Using this endpoint, you can search the ledger
        for events.


        Search results are sorted by `created_at` in descending order.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchLoyaltyEventsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchLoyaltyEventsResponse'
  /v2/loyalty/programs:
    get:
      tags:
        - Loyalty
      summary: ListLoyaltyPrograms
      operationId: ListLoyaltyPrograms
      description: >-
        Returns a list of loyalty programs in the seller's account.

        Loyalty programs define how buyers can earn points and redeem points for
        rewards. Square sellers can have only one loyalty program, which is
        created and managed from the Seller Dashboard. For more information, see
        [Loyalty Program
        Overview](https://developer.squareup.com/docs/loyalty/overview).



        Replaced with
        [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram)
        when used with the keyword `main`.
      x-release-status: DEPRECATED
      deprecated: true
      x-deprecation:
        deprecationDate: '2021-05-13'
        replacedBy: RetrieveLoyaltyProgram
        guideUrl: >-
          https://developer.squareup.com/docs/loyalty-api/overview#migration-notes
      security:
        - oauth2:
            - LOYALTY_READ
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListLoyaltyProgramsResponse'
      x-endpoint-errors:
        - error-code: UNSUPPORTED_LOYALTY_REWARD_TIER
  /v2/loyalty/programs/{program_id}:
    get:
      tags:
        - Loyalty
      summary: RetrieveLoyaltyProgram
      operationId: RetrieveLoyaltyProgram
      description: >-
        Retrieves the loyalty program in a seller's account, specified by the
        program ID or the keyword `main`.


        Loyalty programs define how buyers can earn points and redeem points for
        rewards. Square sellers can have only one loyalty program, which is
        created and managed from the Seller Dashboard. For more information, see
        [Loyalty Program
        Overview](https://developer.squareup.com/docs/loyalty/overview).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_READ
      parameters:
        - name: program_id
          description: >-
            The ID of the loyalty program or the keyword `main`. Either value
            can be used to retrieve the single loyalty program that belongs to
            the seller.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveLoyaltyProgramResponse'
      x-endpoint-errors:
        - error-code: UNSUPPORTED_LOYALTY_REWARD_TIER
  /v2/loyalty/programs/{program_id}/calculate:
    post:
      tags:
        - Loyalty
      summary: CalculateLoyaltyPoints
      operationId: CalculateLoyaltyPoints
      description: >-
        Calculates the number of points a buyer can earn from a purchase.
        Applications might call this endpoint

        to display the points to the buyer.


        - If you are using the Orders API to manage orders, provide the
        `order_id` and (optional) `loyalty_account_id`.

        Square reads the order to compute the points earned from the base
        loyalty program and an associated

        [loyalty promotion](entity:LoyaltyPromotion).


        - If you are not using the Orders API to manage orders, provide
        `transaction_amount_money` with the

        purchase amount. Square uses this amount to calculate the points earned
        from the base loyalty program,

        but not points earned from a loyalty promotion. For spend-based and
        visit-based programs, the `tax_mode`

        setting of the accrual rule indicates how taxes should be treated for
        loyalty points accrual.

        If the purchase qualifies for program points, call

        [ListLoyaltyPromotions](api-endpoint:Loyalty-ListLoyaltyPromotions) and
        perform a client-side computation

        to calculate whether the purchase also qualifies for promotion points.
        For more information, see

        [Calculating promotion
        points](https://developer.squareup.com/docs/loyalty-api/loyalty-promotions#calculate-promotion-points).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_READ
      parameters:
        - name: program_id
          description: >-
            The ID of the [loyalty program](entity:LoyaltyProgram), which
            defines the rules for accruing points.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateLoyaltyPointsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculateLoyaltyPointsResponse'
  /v2/loyalty/programs/{program_id}/promotions:
    get:
      tags:
        - Loyalty
      summary: ListLoyaltyPromotions
      operationId: ListLoyaltyPromotions
      description: >-
        Lists the loyalty promotions associated with a [loyalty
        program](entity:LoyaltyProgram).

        Results are sorted by the `created_at` date in descending order (newest
        to oldest).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_READ
      parameters:
        - name: program_id
          description: >-
            The ID of the base [loyalty program](entity:LoyaltyProgram). To get
            the program ID,

            call
            [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram)
            using the `main` keyword.
          schema:
            type: string
          in: path
          required: true
        - name: status
          description: >-
            The status to filter the results by. If a status is provided, only
            loyalty promotions

            with the specified status are returned. Otherwise, all loyalty
            promotions associated with

            the loyalty program are returned.
          schema:
            $ref: '#/components/schemas/LoyaltyPromotionStatus'
          in: query
          required: false
        - name: cursor
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to return in a single paged response.

            The minimum value is 1 and the maximum value is 30. The default
            value is 30.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListLoyaltyPromotionsResponse'
    post:
      tags:
        - Loyalty
      summary: CreateLoyaltyPromotion
      operationId: CreateLoyaltyPromotion
      description: >-
        Creates a loyalty promotion for a [loyalty
        program](entity:LoyaltyProgram). A loyalty promotion

        enables buyers to earn points in addition to those earned from the base
        loyalty program.


        This endpoint sets the loyalty promotion to the `ACTIVE` or `SCHEDULED`
        status, depending on the

        `available_time` setting. A loyalty program can have a maximum of 10
        loyalty promotions with an

        `ACTIVE` or `SCHEDULED` status.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_WRITE
      parameters:
        - name: program_id
          description: >-
            The ID of the [loyalty program](entity:LoyaltyProgram) to associate
            with the promotion.

            To get the program ID, call
            [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram)

            using the `main` keyword.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLoyaltyPromotionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLoyaltyPromotionResponse'
  /v2/loyalty/programs/{program_id}/promotions/{promotion_id}:
    get:
      tags:
        - Loyalty
      summary: RetrieveLoyaltyPromotion
      operationId: RetrieveLoyaltyPromotion
      description: Retrieves a loyalty promotion.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_READ
      parameters:
        - name: promotion_id
          description: >-
            The ID of the [loyalty promotion](entity:LoyaltyPromotion) to
            retrieve.
          schema:
            type: string
          in: path
          required: true
        - name: program_id
          description: >-
            The ID of the base [loyalty program](entity:LoyaltyProgram). To get
            the program ID,

            call
            [RetrieveLoyaltyProgram](api-endpoint:Loyalty-RetrieveLoyaltyProgram)
            using the `main` keyword.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveLoyaltyPromotionResponse'
  /v2/loyalty/programs/{program_id}/promotions/{promotion_id}/cancel:
    post:
      tags:
        - Loyalty
      summary: CancelLoyaltyPromotion
      operationId: CancelLoyaltyPromotion
      description: >-
        Cancels a loyalty promotion. Use this endpoint to cancel an `ACTIVE`
        promotion earlier than the

        end date, cancel an `ACTIVE` promotion when an end date is not
        specified, or cancel a `SCHEDULED` promotion.

        Because updating a promotion is not supported, you can also use this
        endpoint to cancel a promotion before

        you create a new one.


        This endpoint sets the loyalty promotion to the `CANCELED` state
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_WRITE
      parameters:
        - name: promotion_id
          description: >-
            The ID of the [loyalty promotion](entity:LoyaltyPromotion) to
            cancel. You can cancel a

            promotion that has an `ACTIVE` or `SCHEDULED` status.
          schema:
            type: string
          in: path
          required: true
        - name: program_id
          description: The ID of the base [loyalty program](entity:LoyaltyProgram).
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelLoyaltyPromotionResponse'
  /v2/loyalty/rewards:
    post:
      tags:
        - Loyalty
      summary: CreateLoyaltyReward
      operationId: CreateLoyaltyReward
      description: >-
        Creates a loyalty reward. In the process, the endpoint does following:


        - Uses the `reward_tier_id` in the request to determine the number of
        points

        to lock for this reward.

        - If the request includes `order_id`, it adds the reward and related
        discount to the order.


        After a reward is created, the points are locked and

        not available for the buyer to redeem another reward.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLoyaltyRewardRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLoyaltyRewardResponse'
  /v2/loyalty/rewards/search:
    post:
      tags:
        - Loyalty
      summary: SearchLoyaltyRewards
      operationId: SearchLoyaltyRewards
      description: >-
        Searches for loyalty rewards. This endpoint accepts a request with no
        query filters and returns results for all loyalty accounts.

        If you include a `query` object, `loyalty_account_id` is required and
        `status` is  optional.


        If you know a reward ID, use the

        [RetrieveLoyaltyReward](api-endpoint:Loyalty-RetrieveLoyaltyReward)
        endpoint.


        Search results are sorted by `updated_at` in descending order.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchLoyaltyRewardsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchLoyaltyRewardsResponse'
  /v2/loyalty/rewards/{reward_id}:
    delete:
      tags:
        - Loyalty
      summary: DeleteLoyaltyReward
      operationId: DeleteLoyaltyReward
      description: >-
        Deletes a loyalty reward by doing the following:


        - Returns the loyalty points back to the loyalty account.

        - If an order ID was specified when the reward was created

        (see [CreateLoyaltyReward](api-endpoint:Loyalty-CreateLoyaltyReward)),

        it updates the order by removing the reward and related

        discounts.


        You cannot delete a reward that has reached the terminal state
        (REDEEMED).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_WRITE
      parameters:
        - name: reward_id
          description: The ID of the [loyalty reward](entity:LoyaltyReward) to delete.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteLoyaltyRewardResponse'
    get:
      tags:
        - Loyalty
      summary: RetrieveLoyaltyReward
      operationId: RetrieveLoyaltyReward
      description: Retrieves a loyalty reward.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_READ
      parameters:
        - name: reward_id
          description: The ID of the [loyalty reward](entity:LoyaltyReward) to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveLoyaltyRewardResponse'
  /v2/loyalty/rewards/{reward_id}/redeem:
    post:
      tags:
        - Loyalty
      summary: RedeemLoyaltyReward
      operationId: RedeemLoyaltyReward
      description: |-
        Redeems a loyalty reward.

        The endpoint sets the reward to the `REDEEMED` terminal state.

        If you are using your own order processing system (not using the
        Orders API), you call this endpoint after the buyer paid for the
        purchase.

        After the reward reaches the terminal state, it cannot be deleted.
        In other words, points used for the reward cannot be returned
        to the account.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - LOYALTY_WRITE
      parameters:
        - name: reward_id
          description: The ID of the [loyalty reward](entity:LoyaltyReward) to redeem.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemLoyaltyRewardRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeemLoyaltyRewardResponse'
  /v2/merchants:
    get:
      tags:
        - Merchants
      summary: ListMerchants
      operationId: ListMerchants
      description: >-
        Provides details about the merchant associated with a given access
        token.


        The access token used to connect your application to a Square seller is
        associated

        with a single merchant. That means that `ListMerchants` returns a list

        with a single `Merchant` object. You can specify your personal access
        token

        to get your own merchant information or specify an OAuth token to get
        the

        information for the merchant that granted your application access.


        If you know the merchant ID, you can also use the
        [RetrieveMerchant](api-endpoint:Merchants-RetrieveMerchant)

        endpoint to retrieve the merchant information.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - MERCHANT_PROFILE_READ
      parameters:
        - name: cursor
          description: The cursor generated by the previous response.
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMerchantsResponse'
  /v2/merchants/custom-attribute-definitions:
    get:
      tags:
        - MerchantCustomAttributes
      summary: ListMerchantCustomAttributeDefinitions
      operationId: ListMerchantCustomAttributeDefinitions
      description: >-
        Lists the merchant-related [custom attribute
        definitions](entity:CustomAttributeDefinition) that belong to a Square
        seller account.

        When all response pages are retrieved, the results include all custom
        attribute definitions

        that are visible to the requesting application, including those that are
        created by other

        applications and set to `VISIBILITY_READ_ONLY` or
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_READ
      parameters:
        - name: visibility_filter
          description: >-
            Filters the `CustomAttributeDefinition` results by their
            `visibility` values.
          schema:
            $ref: '#/components/schemas/VisibilityFilter'
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ListMerchantCustomAttributeDefinitionsResponse
    post:
      tags:
        - MerchantCustomAttributes
      summary: CreateMerchantCustomAttributeDefinition
      operationId: CreateMerchantCustomAttributeDefinition
      description: >-
        Creates a merchant-related [custom attribute
        definition](entity:CustomAttributeDefinition) for a Square seller
        account.

        Use this endpoint to define a custom attribute that can be associated
        with a merchant connecting to your application.

        A custom attribute definition specifies the `key`, `visibility`,
        `schema`, and other properties

        for a custom attribute. After the definition is created, you can call

        [UpsertMerchantCustomAttribute](api-endpoint:MerchantCustomAttributes-UpsertMerchantCustomAttribute)
        or

        [BulkUpsertMerchantCustomAttributes](api-endpoint:MerchantCustomAttributes-BulkUpsertMerchantCustomAttributes)

        to set the custom attribute for a merchant.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/CreateMerchantCustomAttributeDefinitionRequest
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/CreateMerchantCustomAttributeDefinitionResponse
  /v2/merchants/custom-attribute-definitions/{key}:
    delete:
      tags:
        - MerchantCustomAttributes
      summary: DeleteMerchantCustomAttributeDefinition
      operationId: DeleteMerchantCustomAttributeDefinition
      description: >-
        Deletes a merchant-related [custom attribute
        definition](entity:CustomAttributeDefinition) from a Square seller
        account.

        Deleting a custom attribute definition also deletes the corresponding
        custom attribute from

        the merchant.

        Only the definition owner can delete a custom attribute definition.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters:
        - name: key
          description: The key of the custom attribute definition to delete.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/DeleteMerchantCustomAttributeDefinitionResponse
    get:
      tags:
        - MerchantCustomAttributes
      summary: RetrieveMerchantCustomAttributeDefinition
      operationId: RetrieveMerchantCustomAttributeDefinition
      description: >-
        Retrieves a merchant-related [custom attribute
        definition](entity:CustomAttributeDefinition) from a Square seller
        account.

        To retrieve a custom attribute definition created by another
        application, the `visibility`

        setting must be `VISIBILITY_READ_ONLY` or
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_READ
      parameters:
        - name: key
          description: >-
            The key of the custom attribute definition to retrieve. If the
            requesting application

            is not the definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
        - name: version
          description: >-
            The current version of the custom attribute definition, which is
            used for strongly consistent

            reads to guarantee that you receive the most up-to-date data. When
            included in the request,

            Square returns the specified version or a higher version if one
            exists. If the specified version

            is higher than the current version, Square returns a `BAD_REQUEST`
            error.
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/RetrieveMerchantCustomAttributeDefinitionResponse
    put:
      tags:
        - MerchantCustomAttributes
      summary: UpdateMerchantCustomAttributeDefinition
      operationId: UpdateMerchantCustomAttributeDefinition
      description: >-
        Updates a merchant-related [custom attribute
        definition](entity:CustomAttributeDefinition) for a Square seller
        account.

        Use this endpoint to update the following fields: `name`, `description`,
        `visibility`, or the

        `schema` for a `Selection` data type.

        Only the definition owner can update a custom attribute definition.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters:
        - name: key
          description: The key of the custom attribute definition to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/UpdateMerchantCustomAttributeDefinitionRequest
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/UpdateMerchantCustomAttributeDefinitionResponse
  /v2/merchants/custom-attributes/bulk-delete:
    post:
      tags:
        - MerchantCustomAttributes
      summary: BulkDeleteMerchantCustomAttributes
      operationId: BulkDeleteMerchantCustomAttributes
      description: >-
        Deletes [custom attributes](entity:CustomAttribute) for a merchant as a
        bulk operation.

        To delete a custom attribute owned by another application, the
        `visibility` setting must be

        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteMerchantCustomAttributesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/BulkDeleteMerchantCustomAttributesResponse
  /v2/merchants/custom-attributes/bulk-upsert:
    post:
      tags:
        - MerchantCustomAttributes
      summary: BulkUpsertMerchantCustomAttributes
      operationId: BulkUpsertMerchantCustomAttributes
      description: >-
        Creates or updates [custom attributes](entity:CustomAttribute) for a
        merchant as a bulk operation.

        Use this endpoint to set the value of one or more custom attributes for
        a merchant.

        A custom attribute is based on a custom attribute definition in a Square
        seller account, which is

        created using the
        [CreateMerchantCustomAttributeDefinition](api-endpoint:MerchantCustomAttributes-CreateMerchantCustomAttributeDefinition)
        endpoint.

        This `BulkUpsertMerchantCustomAttributes` endpoint accepts a map of 1 to
        25 individual upsert

        requests and returns a map of individual upsert responses. Each upsert
        request has a unique ID

        and provides a merchant ID and custom attribute. Each upsert response is
        returned with the ID

        of the corresponding request.

        To create or update a custom attribute owned by another application, the
        `visibility` setting

        must be `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpsertMerchantCustomAttributesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/BulkUpsertMerchantCustomAttributesResponse
  /v2/merchants/{merchant_id}:
    get:
      tags:
        - Merchants
      summary: RetrieveMerchant
      operationId: RetrieveMerchant
      description: Retrieves the `Merchant` object for the given `merchant_id`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - MERCHANT_PROFILE_READ
      parameters:
        - name: merchant_id
          description: >-
            The ID of the merchant to retrieve. If the string "me" is supplied
            as the ID,

            then retrieve the merchant that is currently accessible to this
            call.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveMerchantResponse'
  /v2/merchants/{merchant_id}/custom-attributes:
    get:
      tags:
        - MerchantCustomAttributes
      summary: ListMerchantCustomAttributes
      operationId: ListMerchantCustomAttributes
      description: >-
        Lists the [custom attributes](entity:CustomAttribute) associated with a
        merchant.

        You can use the `with_definitions` query parameter to also retrieve
        custom attribute definitions

        in the same call.

        When all response pages are retrieved, the results include all custom
        attributes that are

        visible to the requesting application, including those that are owned by
        other applications

        and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_READ
      parameters:
        - name: merchant_id
          description: The ID of the target [merchant](entity:Merchant).
          schema:
            type: string
          in: path
          required: true
        - name: visibility_filter
          description: >-
            Filters the `CustomAttributeDefinition` results by their
            `visibility` values.
          schema:
            $ref: '#/components/schemas/VisibilityFilter'
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory.

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100.

            The default value is 20. For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: integer
          in: query
          required: false
        - name: cursor
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint.

            Provide this cursor to retrieve the next page of results for your
            original request. For more

            information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: with_definitions
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of each

            custom attribute. Set this parameter to `true` to get the name and
            description of each custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          schema:
            type: boolean
            default: false
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMerchantCustomAttributesResponse'
  /v2/merchants/{merchant_id}/custom-attributes/{key}:
    delete:
      tags:
        - MerchantCustomAttributes
      summary: DeleteMerchantCustomAttribute
      operationId: DeleteMerchantCustomAttribute
      description: >-
        Deletes a [custom attribute](entity:CustomAttribute) associated with a
        merchant.

        To delete a custom attribute owned by another application, the
        `visibility` setting must be

        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters:
        - name: merchant_id
          description: The ID of the target [merchant](entity:Merchant).
          schema:
            type: string
          in: path
          required: true
        - name: key
          description: >-
            The key of the custom attribute to delete. This key must match the
            `key` of a custom

            attribute definition in the Square seller account. If the requesting
            application is not the

            definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMerchantCustomAttributeResponse'
    get:
      tags:
        - MerchantCustomAttributes
      summary: RetrieveMerchantCustomAttribute
      operationId: RetrieveMerchantCustomAttribute
      description: >-
        Retrieves a [custom attribute](entity:CustomAttribute) associated with a
        merchant.

        You can use the `with_definition` query parameter to also retrieve the
        custom attribute definition

        in the same call.

        To retrieve a custom attribute owned by another application, the
        `visibility` setting must be

        `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_READ
      parameters:
        - name: merchant_id
          description: The ID of the target [merchant](entity:Merchant).
          schema:
            type: string
          in: path
          required: true
        - name: key
          description: >-
            The key of the custom attribute to retrieve. This key must match the
            `key` of a custom

            attribute definition in the Square seller account. If the requesting
            application is not the

            definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
        - name: with_definition
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of

            the custom attribute. Set this parameter to `true` to get the name
            and description of the custom

            attribute, information about the data type, or other definition
            details. The default value is `false`.
          schema:
            type: boolean
            default: false
          in: query
          required: false
        - name: version
          description: >-
            The current version of the custom attribute, which is used for
            strongly consistent reads to

            guarantee that you receive the most up-to-date data. When included
            in the request, Square

            returns the specified version or a higher version if one exists. If
            the specified version is

            higher than the current version, Square returns a `BAD_REQUEST`
            error.
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveMerchantCustomAttributeResponse'
    post:
      tags:
        - MerchantCustomAttributes
      summary: UpsertMerchantCustomAttribute
      operationId: UpsertMerchantCustomAttribute
      description: >-
        Creates or updates a [custom attribute](entity:CustomAttribute) for a
        merchant.

        Use this endpoint to set the value of a custom attribute for a specified
        merchant.

        A custom attribute is based on a custom attribute definition in a Square
        seller account, which

        is created using the
        [CreateMerchantCustomAttributeDefinition](api-endpoint:MerchantCustomAttributes-CreateMerchantCustomAttributeDefinition)
        endpoint.

        To create or update a custom attribute owned by another application, the
        `visibility` setting

        must be `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
      parameters:
        - name: merchant_id
          description: The ID of the target [merchant](entity:Merchant).
          schema:
            type: string
          in: path
          required: true
        - name: key
          description: >-
            The key of the custom attribute to create or update. This key must
            match the `key` of a

            custom attribute definition in the Square seller account. If the
            requesting application is not

            the definition owner, you must use the qualified key.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertMerchantCustomAttributeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertMerchantCustomAttributeResponse'
  /v2/online-checkout/location-settings/{location_id}:
    get:
      tags:
        - Checkout
      summary: RetrieveLocationSettings
      operationId: RetrieveLocationSettings
      description: Retrieves the location-level settings for a Square-hosted checkout page.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_READ
      parameters:
        - name: location_id
          description: The ID of the location for which to retrieve settings.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveLocationSettingsResponse'
    put:
      tags:
        - Checkout
      summary: UpdateLocationSettings
      operationId: UpdateLocationSettings
      description: Updates the location-level settings for a Square-hosted checkout page.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
            - MERCHANT_PROFILE_READ
      parameters:
        - name: location_id
          description: The ID of the location for which to retrieve settings.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateLocationSettingsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateLocationSettingsResponse'
  /v2/online-checkout/merchant-settings:
    get:
      tags:
        - Checkout
      summary: RetrieveMerchantSettings
      operationId: RetrieveMerchantSettings
      description: Retrieves the merchant-level settings for a Square-hosted checkout page.
      x-release-status: BETA
      security:
        - oauth2:
            - PAYMENT_METHODS_READ
            - MERCHANT_PROFILE_READ
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveMerchantSettingsResponse'
    put:
      tags:
        - Checkout
      summary: UpdateMerchantSettings
      operationId: UpdateMerchantSettings
      description: Updates the merchant-level settings for a Square-hosted checkout page.
      x-release-status: BETA
      security:
        - oauth2:
            - MERCHANT_PROFILE_WRITE
            - PAYMENT_METHODS_READ
            - MERCHANT_PROFILE_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMerchantSettingsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateMerchantSettingsResponse'
  /v2/online-checkout/payment-links:
    get:
      tags:
        - Checkout
      summary: ListPaymentLinks
      operationId: ListPaymentLinks
      description: Lists all payment links.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ORDERS_READ
      parameters:
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            If a cursor is not provided, the endpoint returns the first page of
            the results.

            For more  information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            A limit on the number of results to return per page. The limit is
            advisory and

            the implementation might return more or less results. If the
            supplied limit is negative, zero, or

            greater than the maximum limit of 1000, it is ignored.


            Default value: `100`
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPaymentLinksResponse'
    post:
      tags:
        - Checkout
      summary: CreatePaymentLink
      operationId: CreatePaymentLink
      description: >-
        Creates a Square-hosted checkout page. Applications can share the
        resulting payment link with their buyer to pay for goods and services.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
            - ORDERS_READ
            - ORDERS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentLinkRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentLinkResponse'
      x-endpoint-errors:
        - error-code: INVALID_PHONE_NUMBER
        - error-code: INVALID_EMAIL_ADDRESS
        - error-code: MISSING_REQUIRED_PARAMETER
        - error-code: CONFLICTING_PARAMETERS
  /v2/online-checkout/payment-links/{id}:
    delete:
      tags:
        - Checkout
      summary: DeletePaymentLink
      operationId: DeletePaymentLink
      description: Deletes a payment link.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ORDERS_READ
            - ORDERS_WRITE
      parameters:
        - name: id
          description: The ID of the payment link to delete.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePaymentLinkResponse'
    get:
      tags:
        - Checkout
      summary: RetrievePaymentLink
      operationId: RetrievePaymentLink
      description: Retrieves a payment link.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ORDERS_READ
      parameters:
        - name: id
          description: The ID of link to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievePaymentLinkResponse'
    put:
      tags:
        - Checkout
      summary: UpdatePaymentLink
      operationId: UpdatePaymentLink
      description: >-
        Updates a payment link. You can update the `payment_link` fields such as

        `description`, `checkout_options`, and  `pre_populated_data`.

        You cannot update other fields such as the `order_id`, `version`, `URL`,
        or `timestamp` field.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
            - ORDERS_READ
            - ORDERS_WRITE
      parameters:
        - name: id
          description: The ID of the payment link to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePaymentLinkRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePaymentLinkResponse'
      x-endpoint-errors:
        - error-code: INVALID_PHONE_NUMBER
        - error-code: INVALID_EMAIL_ADDRESS
  /v2/orders:
    post:
      tags:
        - Orders
      summary: CreateOrder
      operationId: CreateOrder
      description: >-
        Creates a new [order](entity:Order) that can include information about
        products for

        purchase and settings to apply to the purchase.


        To pay for a created order, see

        [Pay for
        Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders).


        You can modify open orders using the
        [UpdateOrder](api-endpoint:Orders-UpdateOrder) endpoint.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ORDERS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
  /v2/orders/batch-retrieve:
    post:
      tags:
        - Orders
      summary: BatchRetrieveOrders
      operationId: BatchRetrieveOrders
      description: >-
        Retrieves a set of [orders](entity:Order) by their IDs.


        If a given order ID does not exist, the ID is ignored instead of
        generating an error.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ORDERS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRetrieveOrdersRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchRetrieveOrdersResponse'
  /v2/orders/calculate:
    post:
      tags:
        - Orders
      summary: CalculateOrder
      operationId: CalculateOrder
      description: Enables applications to preview order pricing without creating an order.
      x-release-status: BETA
      security:
        - oauth2: []
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateOrderRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculateOrderResponse'
  /v2/orders/clone:
    post:
      tags:
        - Orders
      summary: CloneOrder
      operationId: CloneOrder
      description: >-
        Creates a new order, in the `DRAFT` state, by duplicating an existing
        order. The newly created order has

        only the core fields (such as line items, taxes, and discounts) copied
        from the original order.
      x-release-status: BETA
      security:
        - oauth2:
            - ORDERS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CloneOrderRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloneOrderResponse'
  /v2/orders/custom-attribute-definitions:
    get:
      tags:
        - OrderCustomAttributes
      summary: ListOrderCustomAttributeDefinitions
      operationId: ListOrderCustomAttributeDefinitions
      description: >-
        Lists the order-related [custom attribute
        definitions](entity:CustomAttributeDefinition) that belong to a Square
        seller account.


        When all response pages are retrieved, the results include all custom
        attribute definitions

        that are visible to the requesting application, including those that are
        created by other

        applications and set to `VISIBILITY_READ_ONLY` or
        `VISIBILITY_READ_WRITE_VALUES`. Note that

        seller-defined custom attributes (also known as custom fields) are
        always set to `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - ORDERS_READ
      parameters:
        - name: visibility_filter
          description: >-
            Requests that all of the custom attributes be returned, or only
            those that are read-only or read-write.
          schema:
            $ref: '#/components/schemas/VisibilityFilter'
          in: query
          required: false
        - name: cursor
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint. 

            Provide this cursor to retrieve the next page of results for your
            original request. 

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory. 

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100. 

            The default value is 20.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/ListOrderCustomAttributeDefinitionsResponse
    post:
      tags:
        - OrderCustomAttributes
      summary: CreateOrderCustomAttributeDefinition
      operationId: CreateOrderCustomAttributeDefinition
      description: >-
        Creates an order-related custom attribute definition.  Use this endpoint
        to

        define a custom attribute that can be associated with orders.


        After creating a custom attribute definition, you can set the custom
        attribute for orders

        in the Square seller account.
      x-release-status: BETA
      security:
        - oauth2:
            - ORDERS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderCustomAttributeDefinitionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/CreateOrderCustomAttributeDefinitionResponse
  /v2/orders/custom-attribute-definitions/{key}:
    delete:
      tags:
        - OrderCustomAttributes
      summary: DeleteOrderCustomAttributeDefinition
      operationId: DeleteOrderCustomAttributeDefinition
      description: >-
        Deletes an order-related [custom attribute
        definition](entity:CustomAttributeDefinition) from a Square seller
        account.


        Only the definition owner can delete a custom attribute definition.
      x-release-status: BETA
      security:
        - oauth2:
            - ORDERS_WRITE
      parameters:
        - name: key
          description: The key of the custom attribute definition to delete.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/DeleteOrderCustomAttributeDefinitionResponse
    get:
      tags:
        - OrderCustomAttributes
      summary: RetrieveOrderCustomAttributeDefinition
      operationId: RetrieveOrderCustomAttributeDefinition
      description: >-
        Retrieves an order-related [custom attribute
        definition](entity:CustomAttributeDefinition) from a Square seller
        account.


        To retrieve a custom attribute definition created by another
        application, the `visibility`

        setting must be `VISIBILITY_READ_ONLY` or
        `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom
        attributes

        (also known as custom fields) are always set to
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - ORDERS_READ
      parameters:
        - name: key
          description: The key of the custom attribute definition to retrieve.
          schema:
            type: string
          in: path
          required: true
        - name: version
          description: >-
            To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control, include this optional field and specify the current version
            of the custom attribute.
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/RetrieveOrderCustomAttributeDefinitionResponse
    put:
      tags:
        - OrderCustomAttributes
      summary: UpdateOrderCustomAttributeDefinition
      operationId: UpdateOrderCustomAttributeDefinition
      description: >-
        Updates an order-related custom attribute definition for a Square seller
        account.


        Only the definition owner can update a custom attribute definition. Note
        that sellers can view all custom attributes in exported customer data,
        including those set to `VISIBILITY_HIDDEN`.
      x-release-status: BETA
      security:
        - oauth2:
            - ORDERS_WRITE
      parameters:
        - name: key
          description: The key of the custom attribute definition to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrderCustomAttributeDefinitionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/UpdateOrderCustomAttributeDefinitionResponse
  /v2/orders/custom-attributes/bulk-delete:
    post:
      tags:
        - OrderCustomAttributes
      summary: BulkDeleteOrderCustomAttributes
      operationId: BulkDeleteOrderCustomAttributes
      description: >-
        Deletes order [custom attributes](entity:CustomAttribute) as a bulk
        operation.


        Use this endpoint to delete one or more custom attributes from one or
        more orders.

        A custom attribute is based on a custom attribute definition in a Square
        seller account.  (To create a

        custom attribute definition, use the
        [CreateOrderCustomAttributeDefinition](api-endpoint:OrderCustomAttributes-CreateOrderCustomAttributeDefinition)
        endpoint.)


        This `BulkDeleteOrderCustomAttributes` endpoint accepts a map of 1 to 25
        individual delete

        requests and returns a map of individual delete responses. Each delete
        request has a unique ID

        and provides an order ID and custom attribute. Each delete response is
        returned with the ID

        of the corresponding request.


        To delete a custom attribute owned by another application, the
        `visibility` setting

        must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom
        attributes

        (also known as custom fields) are always set to
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - ORDERS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkDeleteOrderCustomAttributesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkDeleteOrderCustomAttributesResponse'
  /v2/orders/custom-attributes/bulk-upsert:
    post:
      tags:
        - OrderCustomAttributes
      summary: BulkUpsertOrderCustomAttributes
      operationId: BulkUpsertOrderCustomAttributes
      description: >-
        Creates or updates order [custom attributes](entity:CustomAttribute) as
        a bulk operation.


        Use this endpoint to delete one or more custom attributes from one or
        more orders.

        A custom attribute is based on a custom attribute definition in a Square
        seller account.  (To create a

        custom attribute definition, use the
        [CreateOrderCustomAttributeDefinition](api-endpoint:OrderCustomAttributes-CreateOrderCustomAttributeDefinition)
        endpoint.)


        This `BulkUpsertOrderCustomAttributes` endpoint accepts a map of 1 to 25
        individual upsert

        requests and returns a map of individual upsert responses. Each upsert
        request has a unique ID

        and provides an order ID and custom attribute. Each upsert response is
        returned with the ID

        of the corresponding request.


        To create or update a custom attribute owned by another application, the
        `visibility` setting

        must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom
        attributes

        (also known as custom fields) are always set to
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - ORDERS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpsertOrderCustomAttributesRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpsertOrderCustomAttributesResponse'
  /v2/orders/search:
    post:
      tags:
        - Orders
      summary: SearchOrders
      operationId: SearchOrders
      description: >-
        Search all orders for one or more locations. Orders include all sales,

        returns, and exchanges regardless of how or when they entered the Square

        ecosystem (such as Point of Sale, Invoices, and Connect APIs).


        `SearchOrders` requests need to specify which locations to search and
        define a

        [SearchOrdersQuery](entity:SearchOrdersQuery) object that controls

        how to sort or filter the results. Your `SearchOrdersQuery` can:

          Set filter criteria.
          Set the sort order.
          Determine whether to return results as complete `Order` objects or as
        [OrderEntry](entity:OrderEntry) objects.


        Note that details for orders processed with Square Point of Sale while
        in

        offline mode might not be transmitted to Square for up to 72 hours.
        Offline

        orders have a `created_at` value that reflects the time the order was
        created,

        not the time it was subsequently transmitted to Square.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ORDERS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchOrdersRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchOrdersResponse'
  /v2/orders/{order_id}:
    get:
      tags:
        - Orders
      summary: RetrieveOrder
      operationId: RetrieveOrder
      description: Retrieves an [Order](entity:Order) by ID.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ORDERS_READ
      parameters:
        - name: order_id
          description: The ID of the order to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveOrderResponse'
    put:
      tags:
        - Orders
      summary: UpdateOrder
      operationId: UpdateOrder
      description: >-
        Updates an open [order](entity:Order) by adding, replacing, or deleting

        fields. Orders with a `COMPLETED` or `CANCELED` state cannot be updated.


        An `UpdateOrder` request requires the following:


        - The `order_id` in the endpoint path, identifying the order to update.

        - The latest `version` of the order to update.

        - The [sparse
        order](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#sparse-order-objects)

        containing only the fields to update and the version to which the update
        is

        being applied.

        - If deleting fields, the [dot notation
        paths](https://developer.squareup.com/docs/orders-api/manage-orders/update-orders#identifying-fields-to-delete)

        identifying the fields to clear.


        To pay for an order, see

        [Pay for
        Orders](https://developer.squareup.com/docs/orders-api/pay-for-orders).
      x-release-status: BETA
      security:
        - oauth2:
            - ORDERS_WRITE
      parameters:
        - name: order_id
          description: The ID of the order to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrderRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateOrderResponse'
  /v2/orders/{order_id}/custom-attributes:
    get:
      tags:
        - OrderCustomAttributes
      summary: ListOrderCustomAttributes
      operationId: ListOrderCustomAttributes
      description: >-
        Lists the [custom attributes](entity:CustomAttribute) associated with an
        order.


        You can use the `with_definitions` query parameter to also retrieve
        custom attribute definitions

        in the same call.


        When all response pages are retrieved, the results include all custom
        attributes that are

        visible to the requesting application, including those that are owned by
        other applications

        and set to `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - ORDERS_READ
      parameters:
        - name: order_id
          description: The ID of the target [order](entity:Order).
          schema:
            type: string
          in: path
          required: true
        - name: visibility_filter
          description: >-
            Requests that all of the custom attributes be returned, or only
            those that are read-only or read-write.
          schema:
            $ref: '#/components/schemas/VisibilityFilter'
          in: query
          required: false
        - name: cursor
          description: >-
            The cursor returned in the paged response from the previous call to
            this endpoint. 

            Provide this cursor to retrieve the next page of results for your
            original request. 

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to return in a single paged response.
            This limit is advisory. 

            The response might contain more or fewer results. The minimum value
            is 1 and the maximum value is 100. 

            The default value is 20.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/working-with-apis/pagination).
          schema:
            type: integer
          in: query
          required: false
        - name: with_definitions
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of each

            custom attribute. Set this parameter to `true` to get the name and
            description of each custom attribute, 

            information about the data type, or other definition details. The
            default value is `false`.
          schema:
            type: boolean
            default: false
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListOrderCustomAttributesResponse'
  /v2/orders/{order_id}/custom-attributes/{custom_attribute_key}:
    delete:
      tags:
        - OrderCustomAttributes
      summary: DeleteOrderCustomAttribute
      operationId: DeleteOrderCustomAttribute
      description: >-
        Deletes a [custom attribute](entity:CustomAttribute) associated with a
        customer profile.


        To delete a custom attribute owned by another application, the
        `visibility` setting must be

        `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom
        attributes

        (also known as custom fields) are always set to
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - ORDERS_WRITE
      parameters:
        - name: order_id
          description: The ID of the target [order](entity:Order).
          schema:
            type: string
          in: path
          required: true
        - name: custom_attribute_key
          description: >-
            The key of the custom attribute to delete.  This key must match the
            key of an

            existing custom attribute definition.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteOrderCustomAttributeResponse'
    get:
      tags:
        - OrderCustomAttributes
      summary: RetrieveOrderCustomAttribute
      operationId: RetrieveOrderCustomAttribute
      description: >-
        Retrieves a [custom attribute](entity:CustomAttribute) associated with
        an order.


        You can use the `with_definition` query parameter to also retrieve the
        custom attribute definition

        in the same call.


        To retrieve a custom attribute owned by another application, the
        `visibility` setting must be

        `VISIBILITY_READ_ONLY` or `VISIBILITY_READ_WRITE_VALUES`. Note that
        seller-defined custom attributes

        also known as custom fields) are always set to
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - ORDERS_READ
      parameters:
        - name: order_id
          description: The ID of the target [order](entity:Order).
          schema:
            type: string
          in: path
          required: true
        - name: custom_attribute_key
          description: >-
            The key of the custom attribute to retrieve.  This key must match
            the key of an

            existing custom attribute definition.
          schema:
            type: string
          in: path
          required: true
        - name: version
          description: >-
            To enable [optimistic
            concurrency](https://developer.squareup.com/docs/build-basics/common-api-patterns/optimistic-concurrency)

            control, include this optional field and specify the current version
            of the custom attribute.
          schema:
            type: integer
          in: query
          required: false
        - name: with_definition
          description: >-
            Indicates whether to return the [custom attribute
            definition](entity:CustomAttributeDefinition) in the `definition`
            field of each 

            custom attribute. Set this parameter to `true` to get the name and
            description of each custom attribute, 

            information about the data type, or other definition details. The
            default value is `false`.
          schema:
            type: boolean
            default: false
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveOrderCustomAttributeResponse'
    post:
      tags:
        - OrderCustomAttributes
      summary: UpsertOrderCustomAttribute
      operationId: UpsertOrderCustomAttribute
      description: >-
        Creates or updates a [custom attribute](entity:CustomAttribute) for an
        order.


        Use this endpoint to set the value of a custom attribute for a specific
        order.

        A custom attribute is based on a custom attribute definition in a Square
        seller account. (To create a

        custom attribute definition, use the
        [CreateOrderCustomAttributeDefinition](api-endpoint:OrderCustomAttributes-CreateOrderCustomAttributeDefinition)
        endpoint.)


        To create or update a custom attribute owned by another application, the
        `visibility` setting

        must be `VISIBILITY_READ_WRITE_VALUES`. Note that seller-defined custom
        attributes

        (also known as custom fields) are always set to
        `VISIBILITY_READ_WRITE_VALUES`.
      x-release-status: BETA
      security:
        - oauth2:
            - ORDERS_WRITE
      parameters:
        - name: order_id
          description: The ID of the target [order](entity:Order).
          schema:
            type: string
          in: path
          required: true
        - name: custom_attribute_key
          description: >-
            The key of the custom attribute to create or update.  This key must
            match the key 

            of an existing custom attribute definition.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertOrderCustomAttributeRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertOrderCustomAttributeResponse'
  /v2/orders/{order_id}/pay:
    post:
      tags:
        - Orders
      summary: PayOrder
      operationId: PayOrder
      description: >-
        Pay for an [order](entity:Order) using one or more approved
        [payments](entity:Payment)

        or settle an order with a total of `0`.


        The total of the `payment_ids` listed in the request must be equal to
        the order

        total. Orders with a total amount of `0` can be marked as paid by
        specifying an empty

        array of `payment_ids` in the request.


        To be used with `PayOrder`, a payment must:


        - Reference the order by specifying the `order_id` when [creating the
        payment](api-endpoint:Payments-CreatePayment).

        Any approved payments that reference the same `order_id` not specified
        in the

        `payment_ids` is canceled.

        - Be approved with [delayed
        capture](https://developer.squareup.com/docs/payments-api/take-payments/card-payments/delayed-capture).

        Using a delayed capture payment with `PayOrder` completes the approved
        payment.
      x-release-status: BETA
      security:
        - oauth2:
            - PAYMENTS_WRITE
            - ORDERS_WRITE
      parameters:
        - name: order_id
          description: The ID of the order being paid.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayOrderRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayOrderResponse'
  /v2/payments:
    get:
      tags:
        - Payments
      summary: ListPayments
      operationId: ListPayments
      description: >-
        Retrieves a list of payments taken by the account making the request.


        Results are eventually consistent, and new payments or changes to
        payments might take several

        seconds to appear.


        The maximum results per page is 100.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters:
        - name: begin_time
          description: >-
            Indicates the start of the time range to retrieve payments for, in
            RFC 3339 format.  

            The range is determined using the `created_at` field for each
            Payment.

            Inclusive. Default: The current time minus one year.
          schema:
            type: string
          in: query
          required: false
        - name: end_time
          description: >-
            Indicates the end of the time range to retrieve payments for, in RFC
            3339 format.  The 

            range is determined using the `created_at` field for each Payment.


            Default: The current time.
          schema:
            type: string
          in: query
          required: false
        - name: sort_order
          description: >-
            The order in which results are listed by
            `ListPaymentsRequest.sort_field`:

            - `ASC` - Oldest to newest.

            - `DESC` - Newest to oldest (default).
          schema:
            type: string
          in: query
          required: false
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: location_id
          description: >-
            Limit results to the location supplied. By default, results are
            returned

            for the default (main) location associated with the seller.
          schema:
            type: string
          in: query
          required: false
        - name: total
          description: The exact amount in the `total_money` for a payment.
          schema:
            type: integer
            format: int64
          in: query
          required: false
        - name: last_4
          description: The last four digits of a payment card.
          schema:
            type: string
          in: query
          required: false
        - name: card_brand
          description: The brand of the payment card (for example, VISA).
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to be returned in a single page.

            It is possible to receive fewer results than the specified limit on
            a given page.


            The default value of 100 is also the maximum allowed value. If the
            provided value is 

            greater than 100, it is ignored and the default value is used
            instead.


            Default: `100`
          schema:
            type: integer
          in: query
          required: false
        - name: is_offline_payment
          description: Whether the payment was taken offline or not.
          schema:
            type: boolean
            default: false
          in: query
          required: false
        - name: offline_begin_time
          description: >-
            Indicates the start of the time range for which to retrieve offline
            payments, in RFC 3339

            format for timestamps. The range is determined using the

            `offline_payment_details.client_created_at` field for each Payment.
            If set, payments without a

            value set in `offline_payment_details.client_created_at` will not be
            returned.


            Default: The current time.
          schema:
            type: string
          in: query
          required: false
        - name: offline_end_time
          description: >-
            Indicates the end of the time range for which to retrieve offline
            payments, in RFC 3339

            format for timestamps. The range is determined using the

            `offline_payment_details.client_created_at` field for each Payment.
            If set, payments without a

            value set in `offline_payment_details.client_created_at` will not be
            returned.


            Default: The current time.
          schema:
            type: string
          in: query
          required: false
        - name: updated_at_begin_time
          description: >-
            Indicates the start of the time range to retrieve payments for, in
            RFC 3339 format.  The

            range is determined using the `updated_at` field for each Payment.
          schema:
            type: string
          in: query
          required: false
        - name: updated_at_end_time
          description: >-
            Indicates the end of the time range to retrieve payments for, in RFC
            3339 format.  The

            range is determined using the `updated_at` field for each Payment.
          schema:
            type: string
          in: query
          required: false
        - name: sort_field
          description: The field used to sort results by. The default is `CREATED_AT`.
          schema:
            $ref: '#/components/schemas/PaymentSortField'
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPaymentsResponse'
    post:
      tags:
        - Payments
      summary: CreatePayment
      operationId: CreatePayment
      description: >-
        Creates a payment using the provided source. You can use this endpoint 

        to charge a card (credit/debit card or    

        Square gift card) or record a payment that the seller received outside
        of Square 

        (cash payment from a buyer or a payment that an external entity 

        processed on behalf of the seller).


        The endpoint creates a 

        `Payment` object and returns it in the response.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentResponse'
      x-endpoint-errors:
        - error-code: ADDRESS_VERIFICATION_FAILURE
        - error-code: ALLOWABLE_PIN_TRIES_EXCEEDED
        - error-code: APPLE_TTP_PIN_TOKEN
        - error-code: BAD_EXPIRATION
        - error-code: CARDHOLDER_INSUFFICIENT_PERMISSIONS
        - error-code: CARD_DECLINED_VERIFICATION_REQUIRED
        - error-code: CARD_EXPIRED
        - error-code: CARD_NOT_SUPPORTED
        - error-code: CARD_PROCESSING_NOT_ENABLED
        - error-code: CARD_TOKEN_EXPIRED
        - error-code: CARD_TOKEN_USED
        - error-code: CHIP_INSERTION_REQUIRED
        - error-code: CVV_FAILURE
        - error-code: EXPIRATION_FAILURE
        - error-code: GENERIC_DECLINE
        - error-code: GIFT_CARD_AVAILABLE_AMOUNT
        - error-code: INSUFFICIENT_FUNDS
        - error-code: INSUFFICIENT_PERMISSIONS
        - error-code: INVALID_ACCOUNT
        - error-code: INVALID_CARD
        - error-code: INVALID_CARD_DATA
        - error-code: INVALID_EMAIL_ADDRESS
        - error-code: INVALID_EXPIRATION
        - error-code: INVALID_FEES
        - error-code: INVALID_LOCATION
        - error-code: INVALID_PHONE_NUMBER
        - error-code: INVALID_PIN
        - error-code: INVALID_POSTAL_CODE
        - error-code: ISSUER_INSTALLMENT_ERROR
        - error-code: MANUALLY_ENTERED_PAYMENT_NOT_SUPPORTED
        - error-code: PAN_FAILURE
        - error-code: PAYMENT_AMOUNT_MISMATCH
        - error-code: PAYMENT_LIMIT_EXCEEDED
        - error-code: TEMPORARY_ERROR
        - error-code: TRANSACTION_LIMIT
        - error-code: VOICE_FAILURE
  /v2/payments/cancel:
    post:
      tags:
        - Payments
      summary: CancelPaymentByIdempotencyKey
      operationId: CancelPaymentByIdempotencyKey
      description: >-
        Cancels (voids) a payment identified by the idempotency key that is
        specified in the

        request.


        Use this method when the status of a `CreatePayment` request is unknown
        (for example, after you send a

        `CreatePayment` request, a network error occurs and you do not get a
        response). In this case, you can

        direct Square to cancel the payment using this endpoint. In the request,
        you provide the same

        idempotency key that you provided in your `CreatePayment` request that
        you want to cancel. After

        canceling the payment, you can submit your `CreatePayment` request
        again.


        Note that if no payment with the specified idempotency key is found, no
        action is taken and the endpoint

        returns successfully.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelPaymentByIdempotencyKeyRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelPaymentByIdempotencyKeyResponse'
  /v2/payments/{payment_id}:
    get:
      tags:
        - Payments
      summary: GetPayment
      operationId: GetPayment
      description: Retrieves details for a specific payment.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters:
        - name: payment_id
          description: A unique ID for the desired payment.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentResponse'
    put:
      tags:
        - Payments
      summary: UpdatePayment
      operationId: UpdatePayment
      description: |-
        Updates a payment with the APPROVED status.
        You can update the `amount_money` and `tip_money` using this endpoint.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters:
        - name: payment_id
          description: The ID of the payment to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePaymentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdatePaymentResponse'
      x-endpoint-errors:
        - error-code: AMOUNT_TOO_HIGH
        - error-code: CARDHOLDER_INSUFFICIENT_PERMISSIONS
        - error-code: CARD_DECLINED_VERIFICATION_REQUIRED
        - error-code: CARD_EXPIRED
        - error-code: CHIP_INSERTION_REQUIRED
        - error-code: CVV_FAILURE
        - error-code: GENERIC_DECLINE
        - error-code: INSUFFICIENT_FUNDS
        - error-code: INVALID_ACCOUNT
        - error-code: INVALID_FEES
        - error-code: PAN_FAILURE
        - error-code: PAYMENT_LIMIT_EXCEEDED
        - error-code: TEMPORARY_ERROR
        - error-code: TRANSACTION_LIMIT
        - error-code: VOICE_FAILURE
  /v2/payments/{payment_id}/cancel:
    post:
      tags:
        - Payments
      summary: CancelPayment
      operationId: CancelPayment
      description: >-
        Cancels (voids) a payment. You can use this endpoint to cancel a payment
        with 

        the APPROVED `status`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters:
        - name: payment_id
          description: The ID of the payment to cancel.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelPaymentResponse'
  /v2/payments/{payment_id}/complete:
    post:
      tags:
        - Payments
      summary: CompletePayment
      operationId: CompletePayment
      description: >-
        Completes (captures) a payment.

        By default, payments are set to complete immediately after they are
        created.


        You can use this endpoint to complete a payment with the APPROVED
        `status`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters:
        - name: payment_id
          description: The unique ID identifying the payment to be completed.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletePaymentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompletePaymentResponse'
      x-endpoint-errors:
        - error-code: VERSION_MISMATCH
  /v2/payouts:
    get:
      tags:
        - Payouts
      summary: ListPayouts
      operationId: ListPayouts
      description: >-
        Retrieves a list of all payouts for the default location.

        You can filter payouts by location ID, status, time range, and order
        them in ascending or descending order.

        To call this endpoint, set `PAYOUTS_READ` for the OAuth scope.
      x-release-status: PUBLIC
      security:
        - oauth2: []
      parameters:
        - name: location_id
          description: >-
            The ID of the location for which to list the payouts.

            By default, payouts are returned for the default (main) location
            associated with the seller.
          schema:
            type: string
          in: query
          required: false
        - name: status
          description: If provided, only payouts with the given status are returned.
          schema:
            $ref: '#/components/schemas/PayoutStatus'
          in: query
          required: false
        - name: begin_time
          description: >-
            The timestamp for the beginning of the payout creation time, in RFC
            3339 format.

            Inclusive. Default: The current time minus one year.
          schema:
            type: string
          in: query
          required: false
        - name: end_time
          description: >-
            The timestamp for the end of the payout creation time, in RFC 3339
            format.

            Default: The current time.
          schema:
            type: string
          in: query
          required: false
        - name: sort_order
          description: The order in which payouts are listed.
          schema:
            $ref: '#/components/schemas/SortOrder'
          in: query
          required: false
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

            If request parameters change between requests, subsequent results
            may contain duplicates or missing records.
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to be returned in a single page.

            It is possible to receive fewer results than the specified limit on
            a given page.

            The default value of 100 is also the maximum allowed value. If the
            provided value is

            greater than 100, it is ignored and the default value is used
            instead.

            Default: `100`
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPayoutsResponse'
  /v2/payouts/{payout_id}:
    get:
      tags:
        - Payouts
      summary: GetPayout
      operationId: GetPayout
      description: |-
        Retrieves details of a specific payout identified by a payout ID.
        To call this endpoint, set `PAYOUTS_READ` for the OAuth scope.
      x-release-status: PUBLIC
      security:
        - oauth2: []
      parameters:
        - name: payout_id
          description: The ID of the payout to retrieve the information for.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPayoutResponse'
  /v2/payouts/{payout_id}/payout-entries:
    get:
      tags:
        - Payouts
      summary: ListPayoutEntries
      operationId: ListPayoutEntries
      description: |-
        Retrieves a list of all payout entries for a specific payout.
        To call this endpoint, set `PAYOUTS_READ` for the OAuth scope.
      x-release-status: PUBLIC
      security:
        - oauth2: []
      parameters:
        - name: payout_id
          description: The ID of the payout to retrieve the information for.
          schema:
            type: string
          in: path
          required: true
        - name: sort_order
          description: The order in which payout entries are listed.
          schema:
            $ref: '#/components/schemas/SortOrder'
          in: query
          required: false
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.

            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

            If request parameters change between requests, subsequent results
            may contain duplicates or missing records.
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to be returned in a single page.

            It is possible to receive fewer results than the specified limit on
            a given page.

            The default value of 100 is also the maximum allowed value. If the
            provided value is

            greater than 100, it is ignored and the default value is used
            instead.

            Default: `100`
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPayoutEntriesResponse'
  /v2/refunds:
    get:
      tags:
        - Refunds
      summary: ListPaymentRefunds
      operationId: ListPaymentRefunds
      description: >-
        Retrieves a list of refunds for the account making the request.


        Results are eventually consistent, and new refunds or changes to refunds
        might take several

        seconds to appear.


        The maximum results per page is 100.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters:
        - name: begin_time
          description: >-
            Indicates the start of the time range to retrieve each
            `PaymentRefund` for, in RFC 3339 

            format.  The range is determined using the `created_at` field for
            each `PaymentRefund`. 


            Default: The current time minus one year.
          schema:
            type: string
          in: query
          required: false
        - name: end_time
          description: >-
            Indicates the end of the time range to retrieve each `PaymentRefund`
            for, in RFC 3339 

            format.  The range is determined using the `created_at` field for
            each `PaymentRefund`.


            Default: The current time.
          schema:
            type: string
          in: query
          required: false
        - name: sort_order
          description: |-
            The order in which results are listed by `PaymentRefund.created_at`:
            - `ASC` - Oldest to newest.
            - `DESC` - Newest to oldest (default).
          schema:
            type: string
          in: query
          required: false
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this cursor to retrieve the next set of results for the
            original query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: location_id
          description: >-
            Limit results to the location supplied. By default, results are
            returned

            for all locations associated with the seller.
          schema:
            type: string
          in: query
          required: false
        - name: status
          description: >-
            If provided, only refunds with the given status are returned.

            For a list of refund status values, see
            [PaymentRefund](entity:PaymentRefund).


            Default: If omitted, refunds are returned regardless of their
            status.
          schema:
            type: string
          in: query
          required: false
        - name: source_type
          description: >-
            If provided, only returns refunds whose payments have the indicated
            source type.

            Current values include `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, and
            `EXTERNAL`.

            For information about these payment source types, see

            [Take
            Payments](https://developer.squareup.com/docs/payments-api/take-payments).


            Default: If omitted, refunds are returned regardless of the source
            type.
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to be returned in a single page.


            It is possible to receive fewer results than the specified limit on
            a given page.


            If the supplied value is greater than 100, no more than 100 results
            are returned.


            Default: 100
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPaymentRefundsResponse'
    post:
      tags:
        - Refunds
      summary: RefundPayment
      operationId: RefundPayment
      description: >-
        Refunds a payment. You can refund the entire payment amount or a

        portion of it. You can use this endpoint to refund a card payment or
        record a 

        refund of a cash or external payment. For more information, see

        [Refund
        Payment](https://developer.squareup.com/docs/payments-api/refund-payments).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundPaymentRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundPaymentResponse'
      x-endpoint-errors:
        - error-code: CARD_MISMATCH
        - error-code: CARD_PRESENCE_REQUIRED
        - error-code: CARD_TOKEN_USED
        - error-code: GENERIC_DECLINE
        - error-code: INSUFFICIENT_PERMISSIONS_FOR_REFUND
        - error-code: INVALID_CARD
        - error-code: INVALID_CARD_DATA
        - error-code: INVALID_FEES
        - error-code: PAYMENT_NOT_REFUNDABLE
        - error-code: PAYMENT_NOT_REFUNDABLE_DUE_TO_DISPUTE
        - error-code: REFUND_AMOUNT_INVALID
        - error-code: REFUND_DECLINED
        - error-code: UNSUPPORTED_CARD_BRAND
        - error-code: UNSUPPORTED_COUNTRY
        - error-code: UNSUPPORTED_CURRENCY
        - error-code: UNSUPPORTED_INSTRUMENT_TYPE
        - error-code: UNSUPPORTED_SOURCE_TYPE
        - error-code: VALUE_TOO_HIGH
        - error-code: VERSION_MISMATCH
  /v2/refunds/{refund_id}:
    get:
      tags:
        - Refunds
      summary: GetPaymentRefund
      operationId: GetPaymentRefund
      description: Retrieves a specific refund using the `refund_id`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters:
        - name: refund_id
          description: The unique ID for the desired `PaymentRefund`.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPaymentRefundResponse'
  /v2/sites:
    get:
      tags:
        - Sites
      summary: ListSites
      operationId: ListSites
      description: >-
        Lists the Square Online sites that belong to a seller. Sites are listed
        in descending order by the `created_at` date.



        __Note:__ Square Online APIs are publicly available as part of an early
        access program. For more information, see [Early access program for
        Square Online
        APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ONLINE_STORE_SITE_READ
      parameters: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSitesResponse'
  /v2/sites/{site_id}/snippet:
    delete:
      tags:
        - Snippets
      summary: DeleteSnippet
      operationId: DeleteSnippet
      description: >-
        Removes your snippet from a Square Online site.


        You can call [ListSites](api-endpoint:Sites-ListSites) to get the IDs of
        the sites that belong to a seller.



        __Note:__ Square Online APIs are publicly available as part of an early
        access program. For more information, see [Early access program for
        Square Online
        APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ONLINE_STORE_SNIPPETS_WRITE
      parameters:
        - name: site_id
          description: The ID of the site that contains the snippet.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteSnippetResponse'
    get:
      tags:
        - Snippets
      summary: RetrieveSnippet
      operationId: RetrieveSnippet
      description: >-
        Retrieves your snippet from a Square Online site. A site can contain
        snippets from multiple snippet applications, but you can retrieve only
        the snippet that was added by your application.


        You can call [ListSites](api-endpoint:Sites-ListSites) to get the IDs of
        the sites that belong to a seller.



        __Note:__ Square Online APIs are publicly available as part of an early
        access program. For more information, see [Early access program for
        Square Online
        APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ONLINE_STORE_SNIPPETS_READ
      parameters:
        - name: site_id
          description: The ID of the site that contains the snippet.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveSnippetResponse'
    post:
      tags:
        - Snippets
      summary: UpsertSnippet
      operationId: UpsertSnippet
      description: >-
        Adds a snippet to a Square Online site or updates the existing snippet
        on the site. 

        The snippet code is appended to the end of the `head` element on every
        page of the site, except checkout pages. A snippet application can add
        one snippet to a given site. 


        You can call [ListSites](api-endpoint:Sites-ListSites) to get the IDs of
        the sites that belong to a seller.



        __Note:__ Square Online APIs are publicly available as part of an early
        access program. For more information, see [Early access program for
        Square Online
        APIs](https://developer.squareup.com/docs/online-api#early-access-program-for-square-online-apis).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - ONLINE_STORE_SNIPPETS_WRITE
      parameters:
        - name: site_id
          description: The ID of the site where you want to add or update the snippet.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertSnippetRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertSnippetResponse'
  /v2/subscriptions:
    post:
      tags:
        - Subscriptions
      summary: CreateSubscription
      operationId: CreateSubscription
      description: >-
        Enrolls a customer in a subscription.


        If you provide a card on file in the request, Square charges the card
        for

        the subscription. Otherwise, Square sends an invoice to the customer's
        email

        address. The subscription starts immediately, unless the request
        includes

        the optional `start_date`. Each individual subscription is associated
        with a particular location.


        For more information, see [Create a
        subscription](https://developer.squareup.com/docs/subscriptions-api/manage-subscriptions#create-a-subscription).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
            - PAYMENTS_WRITE
            - SUBSCRIPTIONS_WRITE
            - ITEMS_READ
            - ORDERS_WRITE
            - INVOICES_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSubscriptionResponse'
      x-endpoint-errors:
        - error-code: CARD_PROCESSING_NOT_ENABLED
        - error-code: CUSTOMER_MISSING_EMAIL
        - error-code: CUSTOMER_MISSING_NAME
        - error-code: CUSTOMER_NOT_FOUND
        - error-code: INVALID_CARD
        - error-code: INVALID_DATE
  /v2/subscriptions/bulk-swap-plan:
    post:
      tags:
        - Subscriptions
      summary: BulkSwapPlan
      operationId: BulkSwapPlan
      description: >-
        Schedules a plan variation change for all active subscriptions under a
        given plan

        variation. For more information, see [Swap Subscription Plan
        Variations](https://developer.squareup.com/docs/subscriptions-api/swap-plan-variations).
      x-release-status: BETA
      security:
        - oauth2:
            - SUBSCRIPTIONS_WRITE
            - SUBSCRIPTIONS_READ
            - ITEMS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkSwapPlanRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkSwapPlanResponse'
      x-endpoint-errors:
        - error-code: CARD_PROCESSING_NOT_ENABLED
        - error-code: CUSTOMER_NOT_FOUND
  /v2/subscriptions/search:
    post:
      tags:
        - Subscriptions
      summary: SearchSubscriptions
      operationId: SearchSubscriptions
      description: >-
        Searches for subscriptions.


        Results are ordered chronologically by subscription creation date. If

        the request specifies more than one location ID,

        the endpoint orders the result

        by location ID, and then by creation date within each location. If no
        locations are given

        in the query, all locations are searched.


        You can also optionally specify `customer_ids` to search by customer.

        If left unset, all customers

        associated with the specified locations are returned.

        If the request specifies customer IDs, the endpoint orders results

        first by location, within location by customer ID, and within

        customer by subscription creation date.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - SUBSCRIPTIONS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchSubscriptionsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchSubscriptionsResponse'
      x-endpoint-errors:
        - error-code: CUSTOMER_NOT_FOUND
  /v2/subscriptions/{subscription_id}:
    get:
      tags:
        - Subscriptions
      summary: RetrieveSubscription
      operationId: RetrieveSubscription
      description: Retrieves a specific subscription.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - SUBSCRIPTIONS_READ
      parameters:
        - name: subscription_id
          description: The ID of the subscription to retrieve.
          schema:
            type: string
          in: path
          required: true
        - name: include
          description: >-
            A query parameter to specify related information to be included in
            the response. 


            The supported query parameter values are: 


            - `actions`: to include scheduled actions on the targeted
            subscription.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveSubscriptionResponse'
    put:
      tags:
        - Subscriptions
      summary: UpdateSubscription
      operationId: UpdateSubscription
      description: >-
        Updates a subscription by modifying or clearing `subscription` field
        values.

        To clear a field, set its value to `null`.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
            - PAYMENTS_WRITE
            - SUBSCRIPTIONS_WRITE
            - ITEMS_READ
            - ORDERS_WRITE
            - INVOICES_WRITE
      parameters:
        - name: subscription_id
          description: The ID of the subscription to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateSubscriptionResponse'
      x-endpoint-errors:
        - error-code: CUSTOMER_NOT_FOUND
        - error-code: INVALID_CARD
  /v2/subscriptions/{subscription_id}/actions/{action_id}:
    delete:
      tags:
        - Subscriptions
      summary: DeleteSubscriptionAction
      operationId: DeleteSubscriptionAction
      description: Deletes a scheduled action for a subscription.
      x-release-status: BETA
      security:
        - oauth2:
            - SUBSCRIPTIONS_WRITE
      parameters:
        - name: subscription_id
          description: The ID of the subscription the targeted action is to act upon.
          schema:
            type: string
          in: path
          required: true
        - name: action_id
          description: The ID of the targeted action to be deleted.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteSubscriptionActionResponse'
  /v2/subscriptions/{subscription_id}/billing-anchor:
    post:
      tags:
        - Subscriptions
      summary: ChangeBillingAnchorDate
      operationId: ChangeBillingAnchorDate
      description: >-
        Changes the [billing anchor
        date](https://developer.squareup.com/docs/subscriptions-api/subscription-billing#billing-dates)

        for a subscription.
      x-release-status: BETA
      security:
        - oauth2:
            - SUBSCRIPTIONS_WRITE
            - SUBSCRIPTIONS_READ
            - ITEMS_READ
      parameters:
        - name: subscription_id
          description: The ID of the subscription to update the billing anchor date.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChangeBillingAnchorDateRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeBillingAnchorDateResponse'
  /v2/subscriptions/{subscription_id}/cancel:
    post:
      tags:
        - Subscriptions
      summary: CancelSubscription
      operationId: CancelSubscription
      description: >-
        Schedules a `CANCEL` action to cancel an active subscription. This 

        sets the `canceled_date` field to the end of the active billing period.
        After this date, 

        the subscription status changes from ACTIVE to CANCELED.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - SUBSCRIPTIONS_WRITE
      parameters:
        - name: subscription_id
          description: The ID of the subscription to cancel.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelSubscriptionResponse'
  /v2/subscriptions/{subscription_id}/events:
    get:
      tags:
        - Subscriptions
      summary: ListSubscriptionEvents
      operationId: ListSubscriptionEvents
      description: >-
        Lists all
        [events](https://developer.squareup.com/docs/subscriptions-api/actions-events)
        for a specific subscription.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - SUBSCRIPTIONS_READ
      parameters:
        - name: subscription_id
          description: The ID of the subscription to retrieve the events for.
          schema:
            type: string
          in: path
          required: true
        - name: cursor
          description: >-
            When the total number of resulting subscription events exceeds the
            limit of a paged response, 

            specify the cursor returned from a preceding response here to fetch
            the next set of results.

            If the cursor is unset, the response contains the last page of the
            results.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: limit
          description: |-
            The upper limit on the number of subscription events to return
            in a paged response.
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSubscriptionEventsResponse'
  /v2/subscriptions/{subscription_id}/pause:
    post:
      tags:
        - Subscriptions
      summary: PauseSubscription
      operationId: PauseSubscription
      description: Schedules a `PAUSE` action to pause an active subscription.
      x-release-status: BETA
      security:
        - oauth2:
            - CUSTOMERS_READ
            - PAYMENTS_WRITE
            - SUBSCRIPTIONS_WRITE
            - ITEMS_READ
            - ORDERS_WRITE
            - INVOICES_WRITE
      parameters:
        - name: subscription_id
          description: The ID of the subscription to pause.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PauseSubscriptionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PauseSubscriptionResponse'
      x-endpoint-errors:
        - error-code: CARD_PROCESSING_NOT_ENABLED
        - error-code: CUSTOMER_NOT_FOUND
        - error-code: INVALID_PAUSE_LENGTH
        - error-code: INVALID_DATE
  /v2/subscriptions/{subscription_id}/resume:
    post:
      tags:
        - Subscriptions
      summary: ResumeSubscription
      operationId: ResumeSubscription
      description: >-
        Schedules a `RESUME` action to resume a paused or a deactivated
        subscription.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - CUSTOMERS_READ
            - PAYMENTS_WRITE
            - SUBSCRIPTIONS_WRITE
            - ITEMS_READ
            - ORDERS_WRITE
            - INVOICES_WRITE
      parameters:
        - name: subscription_id
          description: The ID of the subscription to resume.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeSubscriptionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeSubscriptionResponse'
      x-endpoint-errors:
        - error-code: CARD_PROCESSING_NOT_ENABLED
        - error-code: CUSTOMER_MISSING_EMAIL
        - error-code: CUSTOMER_MISSING_NAME
        - error-code: CUSTOMER_NOT_FOUND
        - error-code: INVALID_CARD
        - error-code: INVALID_DATE
  /v2/subscriptions/{subscription_id}/swap-plan:
    post:
      tags:
        - Subscriptions
      summary: SwapPlan
      operationId: SwapPlan
      description: >-
        Schedules a `SWAP_PLAN` action to swap a subscription plan variation in
        an existing subscription. 

        For more information, see [Swap Subscription Plan
        Variations](https://developer.squareup.com/docs/subscriptions-api/swap-plan-variations).
      x-release-status: BETA
      security:
        - oauth2:
            - CUSTOMERS_READ
            - PAYMENTS_WRITE
            - SUBSCRIPTIONS_WRITE
            - ITEMS_READ
            - ORDERS_WRITE
            - INVOICES_WRITE
      parameters:
        - name: subscription_id
          description: The ID of the subscription to swap the subscription plan for.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwapPlanRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SwapPlanResponse'
      x-endpoint-errors:
        - error-code: CARD_PROCESSING_NOT_ENABLED
        - error-code: CUSTOMER_NOT_FOUND
  /v2/team-members:
    post:
      tags:
        - Team
      summary: CreateTeamMember
      operationId: CreateTeamMember
      description: >-
        Creates a single `TeamMember` object. The `TeamMember` object is
        returned on successful creates.

        You must provide the following values in your request to this endpoint:

        - `given_name`

        - `family_name`


        Learn about [Troubleshooting the Team
        API](https://developer.squareup.com/docs/team/troubleshooting#createteammember).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - EMPLOYEES_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTeamMemberRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTeamMemberResponse'
      x-endpoint-errors:
        - error-code: INVALID_EMAIL_ADDRESS
        - error-code: BAD_REQUEST
        - error-code: FORBIDDEN
  /v2/team-members/bulk-create:
    post:
      tags:
        - Team
      summary: BulkCreateTeamMembers
      operationId: BulkCreateTeamMembers
      description: >-
        Creates multiple `TeamMember` objects. The created `TeamMember` objects
        are returned on successful creates.

        This process is non-transactional and processes as much of the request
        as possible. If one of the creates in

        the request cannot be successfully processed, the request is not marked
        as failed, but the body of the response

        contains explicit error information for the failed create.


        Learn about [Troubleshooting the Team
        API](https://developer.squareup.com/docs/team/troubleshooting#bulk-create-team-members).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - EMPLOYEES_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkCreateTeamMembersRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkCreateTeamMembersResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: FORBIDDEN
  /v2/team-members/bulk-update:
    post:
      tags:
        - Team
      summary: BulkUpdateTeamMembers
      operationId: BulkUpdateTeamMembers
      description: >-
        Updates multiple `TeamMember` objects. The updated `TeamMember` objects
        are returned on successful updates.

        This process is non-transactional and processes as much of the request
        as possible. If one of the updates in

        the request cannot be successfully processed, the request is not marked
        as failed, but the body of the response

        contains explicit error information for the failed update.

        Learn about [Troubleshooting the Team
        API](https://developer.squareup.com/docs/team/troubleshooting#bulk-update-team-members).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - EMPLOYEES_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpdateTeamMembersRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpdateTeamMembersResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: FORBIDDEN
  /v2/team-members/jobs:
    get:
      tags:
        - Team
      summary: ListJobs
      operationId: ListJobs
      description: >-
        Lists jobs in a seller account. Results are sorted by title in ascending
        order.
      x-release-status: BETA
      security:
        - oauth2:
            - EMPLOYEES_READ
      parameters:
        - name: cursor
          description: >-
            The pagination cursor returned by the previous call to this
            endpoint. Provide this

            cursor to retrieve the next page of results for your original
            request. For more information,

            see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListJobsResponse'
    post:
      tags:
        - Team
      summary: CreateJob
      operationId: CreateJob
      description: >-
        Creates a job in a seller account. A job defines a title and tip
        eligibility. Note that

        compensation is defined in a [job assignment](entity:JobAssignment) in a
        team member's wage setting.
      x-release-status: BETA
      security:
        - oauth2:
            - EMPLOYEES_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateJobResponse'
  /v2/team-members/jobs/{job_id}:
    get:
      tags:
        - Team
      summary: RetrieveJob
      operationId: RetrieveJob
      description: Retrieves a specified job.
      x-release-status: BETA
      security:
        - oauth2:
            - EMPLOYEES_READ
      parameters:
        - name: job_id
          description: The ID of the job to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveJobResponse'
    put:
      tags:
        - Team
      summary: UpdateJob
      operationId: UpdateJob
      description: >-
        Updates the title or tip eligibility of a job. Changes to the title
        propagate to all

        `JobAssignment`, `Shift`, and `TeamMemberWage` objects that reference
        the job ID. Changes to

        tip eligibility propagate to all `TeamMemberWage` objects that reference
        the job ID.
      x-release-status: BETA
      security:
        - oauth2:
            - EMPLOYEES_WRITE
      parameters:
        - name: job_id
          description: The ID of the job to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateJobRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateJobResponse'
  /v2/team-members/search:
    post:
      tags:
        - Team
      summary: SearchTeamMembers
      operationId: SearchTeamMembers
      description: >-
        Returns a paginated list of `TeamMember` objects for a business. 

        The list can be filtered by location IDs, `ACTIVE` or `INACTIVE` status,
        or whether

        the team member is the Square account owner.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - EMPLOYEES_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchTeamMembersRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchTeamMembersResponse'
  /v2/team-members/{team_member_id}:
    get:
      tags:
        - Team
      summary: RetrieveTeamMember
      operationId: RetrieveTeamMember
      description: >-
        Retrieves a `TeamMember` object for the given `TeamMember.id`.

        Learn about [Troubleshooting the Team
        API](https://developer.squareup.com/docs/team/troubleshooting#retrieve-a-team-member).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - EMPLOYEES_READ
      parameters:
        - name: team_member_id
          description: The ID of the team member to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveTeamMemberResponse'
    put:
      tags:
        - Team
      summary: UpdateTeamMember
      operationId: UpdateTeamMember
      description: >-
        Updates a single `TeamMember` object. The `TeamMember` object is
        returned on successful updates.

        Learn about [Troubleshooting the Team
        API](https://developer.squareup.com/docs/team/troubleshooting#update-a-team-member).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - EMPLOYEES_WRITE
      parameters:
        - name: team_member_id
          description: The ID of the team member to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTeamMemberRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateTeamMemberResponse'
      x-endpoint-errors:
        - error-code: INVALID_EMAIL_ADDRESS
        - error-code: BAD_REQUEST
        - error-code: FORBIDDEN
  /v2/team-members/{team_member_id}/wage-setting:
    get:
      tags:
        - Team
      summary: RetrieveWageSetting
      operationId: RetrieveWageSetting
      description: >-
        Retrieves a `WageSetting` object for a team member specified

        by `TeamMember.id`. For more information, see

        [Troubleshooting the Team
        API](https://developer.squareup.com/docs/team/troubleshooting#retrievewagesetting).


        Square recommends using
        [RetrieveTeamMember](api-endpoint:Team-RetrieveTeamMember) or
        [SearchTeamMembers](api-endpoint:Team-SearchTeamMembers)

        to get this information directly from the `TeamMember.wage_setting`
        field.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - EMPLOYEES_READ
      parameters:
        - name: team_member_id
          description: The ID of the team member for which to retrieve the wage setting.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveWageSettingResponse'
    put:
      tags:
        - Team
      summary: UpdateWageSetting
      operationId: UpdateWageSetting
      description: >-
        Creates or updates a `WageSetting` object. The object is created if a

        `WageSetting` with the specified `team_member_id` doesn't exist.
        Otherwise,

        it fully replaces the `WageSetting` object for the team member.

        The `WageSetting` is returned on a successful update. For more
        information, see

        [Troubleshooting the Team
        API](https://developer.squareup.com/docs/team/troubleshooting#create-or-update-a-wage-setting).


        Square recommends using
        [CreateTeamMember](api-endpoint:Team-CreateTeamMember) or
        [UpdateTeamMember](api-endpoint:Team-UpdateTeamMember)

        to manage the `TeamMember.wage_setting` field directly.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - EMPLOYEES_WRITE
      parameters:
        - name: team_member_id
          description: >-
            The ID of the team member for which to update the `WageSetting`
            object.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWageSettingRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateWageSettingResponse'
  /v2/terminals/actions:
    post:
      tags:
        - Terminal
      summary: CreateTerminalAction
      operationId: CreateTerminalAction
      description: Creates a Terminal action request and sends it to the specified device.
      x-release-status: BETA
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTerminalActionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTerminalActionResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: IDEMPOTENCY_KEY_REUSED
        - error-code: INVALID_LOCATION
        - error-code: INVALID_VALUE
        - error-code: UNAUTHORIZED
  /v2/terminals/actions/search:
    post:
      tags:
        - Terminal
      summary: SearchTerminalActions
      operationId: SearchTerminalActions
      description: >-
        Retrieves a filtered list of Terminal action requests created by the
        account making the request. Terminal action requests are available for
        30 days.
      x-release-status: BETA
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchTerminalActionsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchTerminalActionsResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: INVALID_CURSOR
        - error-code: UNKNOWN_QUERY_PARAMETER
  /v2/terminals/actions/{action_id}:
    get:
      tags:
        - Terminal
      summary: GetTerminalAction
      operationId: GetTerminalAction
      description: >-
        Retrieves a Terminal action request by `action_id`. Terminal action
        requests are available for 30 days.
      x-release-status: BETA
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters:
        - name: action_id
          description: Unique ID for the desired `TerminalAction`.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTerminalActionResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: NOT_FOUND
  /v2/terminals/actions/{action_id}/cancel:
    post:
      tags:
        - Terminal
      summary: CancelTerminalAction
      operationId: CancelTerminalAction
      description: >-
        Cancels a Terminal action request if the status of the request permits
        it.
      x-release-status: BETA
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters:
        - name: action_id
          description: Unique ID for the desired `TerminalAction`.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelTerminalActionResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: NOT_FOUND
        - error-code: TEMPORARY_ERROR
  /v2/terminals/actions/{action_id}/dismiss:
    post:
      tags:
        - Terminal
      summary: DismissTerminalAction
      operationId: DismissTerminalAction
      description: >-
        Dismisses a Terminal action request if the status and type of the
        request permits it.


        See [Link and Dismiss
        Actions](https://developer.squareup.com/docs/terminal-api/advanced-features/custom-workflows/link-and-dismiss-actions)
        for more details.
      x-release-status: BETA
      security:
        - oauth2: []
      parameters:
        - name: action_id
          description: >-
            Unique ID for the `TerminalAction` associated with the action to be
            dismissed.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DismissTerminalActionResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: NOT_FOUND
  /v2/terminals/checkouts:
    post:
      tags:
        - Terminal
      summary: CreateTerminalCheckout
      operationId: CreateTerminalCheckout
      description: >-
        Creates a Terminal checkout request and sends it to the specified device
        to take a payment

        for the requested amount.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTerminalCheckoutRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTerminalCheckoutResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: IDEMPOTENCY_KEY_REUSED
        - error-code: INVALID_FEES
        - error-code: INVALID_LOCATION
        - error-code: INVALID_VALUE
        - error-code: UNAUTHORIZED
  /v2/terminals/checkouts/search:
    post:
      tags:
        - Terminal
      summary: SearchTerminalCheckouts
      operationId: SearchTerminalCheckouts
      description: >-
        Returns a filtered list of Terminal checkout requests created by the
        application making the request. Only Terminal checkout requests created
        for the merchant scoped to the OAuth token are returned. Terminal
        checkout requests are available for 30 days.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchTerminalCheckoutsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchTerminalCheckoutsResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: INVALID_CURSOR
        - error-code: UNKNOWN_QUERY_PARAMETER
  /v2/terminals/checkouts/{checkout_id}:
    get:
      tags:
        - Terminal
      summary: GetTerminalCheckout
      operationId: GetTerminalCheckout
      description: >-
        Retrieves a Terminal checkout request by `checkout_id`. Terminal
        checkout requests are available for 30 days.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters:
        - name: checkout_id
          description: The unique ID for the desired `TerminalCheckout`.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTerminalCheckoutResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: NOT_FOUND
  /v2/terminals/checkouts/{checkout_id}/cancel:
    post:
      tags:
        - Terminal
      summary: CancelTerminalCheckout
      operationId: CancelTerminalCheckout
      description: >-
        Cancels a Terminal checkout request if the status of the request permits
        it.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters:
        - name: checkout_id
          description: The unique ID for the desired `TerminalCheckout`.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelTerminalCheckoutResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: NOT_FOUND
  /v2/terminals/checkouts/{checkout_id}/dismiss:
    post:
      tags:
        - Terminal
      summary: DismissTerminalCheckout
      operationId: DismissTerminalCheckout
      description: >-
        Dismisses a Terminal checkout request if the status and type of the
        request permits it.
      x-release-status: BETA
      security:
        - oauth2: []
      parameters:
        - name: checkout_id
          description: >-
            Unique ID for the `TerminalCheckout` associated with the checkout to
            be dismissed.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DismissTerminalCheckoutResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: NOT_FOUND
  /v2/terminals/refunds:
    post:
      tags:
        - Terminal
      summary: CreateTerminalRefund
      operationId: CreateTerminalRefund
      description: >-
        Creates a request to refund an Interac payment completed on a Square
        Terminal. Refunds for Interac payments on a Square Terminal are
        supported only for Interac debit cards in Canada. Other refunds for
        Terminal payments should use the Refunds API. For more information, see
        [Refunds API](api:Refunds).
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTerminalRefundRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTerminalRefundResponse'
  /v2/terminals/refunds/search:
    post:
      tags:
        - Terminal
      summary: SearchTerminalRefunds
      operationId: SearchTerminalRefunds
      description: >-
        Retrieves a filtered list of Interac Terminal refund requests created by
        the seller making the request. Terminal refund requests are available
        for 30 days.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchTerminalRefundsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchTerminalRefundsResponse'
  /v2/terminals/refunds/{terminal_refund_id}:
    get:
      tags:
        - Terminal
      summary: GetTerminalRefund
      operationId: GetTerminalRefund
      description: >-
        Retrieves an Interac Terminal refund object by ID. Terminal refund
        objects are available for 30 days.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_READ
      parameters:
        - name: terminal_refund_id
          description: The unique ID for the desired `TerminalRefund`.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTerminalRefundResponse'
  /v2/terminals/refunds/{terminal_refund_id}/cancel:
    post:
      tags:
        - Terminal
      summary: CancelTerminalRefund
      operationId: CancelTerminalRefund
      description: >-
        Cancels an Interac Terminal refund request by refund request ID if the
        status of the request permits it.
      x-release-status: PUBLIC
      security:
        - oauth2:
            - PAYMENTS_WRITE
      parameters:
        - name: terminal_refund_id
          description: The unique ID for the desired `TerminalRefund`.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelTerminalRefundResponse'
  /v2/terminals/refunds/{terminal_refund_id}/dismiss:
    post:
      tags:
        - Terminal
      summary: DismissTerminalRefund
      operationId: DismissTerminalRefund
      description: >-
        Dismisses a Terminal refund request if the status and type of the
        request permits it.
      x-release-status: BETA
      security:
        - oauth2: []
      parameters:
        - name: terminal_refund_id
          description: >-
            Unique ID for the `TerminalRefund` associated with the refund to be
            dismissed.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DismissTerminalRefundResponse'
      x-endpoint-errors:
        - error-code: BAD_REQUEST
        - error-code: NOT_FOUND
  /v2/vendors/bulk-create:
    post:
      tags:
        - Vendors
      summary: BulkCreateVendors
      operationId: BulkCreateVendors
      description: >-
        Creates one or more [Vendor](entity:Vendor) objects to represent
        suppliers to a seller.
      x-release-status: BETA
      security:
        - oauth2:
            - VENDOR_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkCreateVendorsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkCreateVendorsResponse'
  /v2/vendors/bulk-retrieve:
    post:
      tags:
        - Vendors
      summary: BulkRetrieveVendors
      operationId: BulkRetrieveVendors
      description: Retrieves one or more vendors of specified [Vendor](entity:Vendor) IDs.
      x-release-status: BETA
      security:
        - oauth2:
            - VENDOR_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkRetrieveVendorsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkRetrieveVendorsResponse'
  /v2/vendors/bulk-update:
    put:
      tags:
        - Vendors
      summary: BulkUpdateVendors
      operationId: BulkUpdateVendors
      description: >-
        Updates one or more of existing [Vendor](entity:Vendor) objects as
        suppliers to a seller.
      x-release-status: BETA
      security:
        - oauth2:
            - VENDOR_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkUpdateVendorsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkUpdateVendorsResponse'
  /v2/vendors/create:
    post:
      tags:
        - Vendors
      summary: CreateVendor
      operationId: CreateVendor
      description: >-
        Creates a single [Vendor](entity:Vendor) object to represent a supplier
        to a seller.
      x-release-status: BETA
      security:
        - oauth2:
            - VENDOR_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateVendorRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateVendorResponse'
  /v2/vendors/search:
    post:
      tags:
        - Vendors
      summary: SearchVendors
      operationId: SearchVendors
      description: >-
        Searches for vendors using a filter against supported
        [Vendor](entity:Vendor) properties and a supported sorter.
      x-release-status: BETA
      security:
        - oauth2:
            - VENDOR_READ
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchVendorsRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchVendorsResponse'
  /v2/vendors/{vendor_id}:
    get:
      tags:
        - Vendors
      summary: RetrieveVendor
      operationId: RetrieveVendor
      description: Retrieves the vendor of a specified [Vendor](entity:Vendor) ID.
      x-release-status: BETA
      security:
        - oauth2:
            - VENDOR_READ
      parameters:
        - name: vendor_id
          description: ID of the [Vendor](entity:Vendor) to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveVendorResponse'
    put:
      tags:
        - Vendors
      summary: UpdateVendor
      operationId: UpdateVendor
      description: >-
        Updates an existing [Vendor](entity:Vendor) object as a supplier to a
        seller.
      x-release-status: BETA
      security:
        - oauth2:
            - VENDOR_WRITE
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateVendorRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateVendorResponse'
  /v2/webhooks/event-types:
    get:
      tags:
        - WebhookSubscriptions
      summary: ListWebhookEventTypes
      operationId: ListWebhookEventTypes
      description: Lists all webhook event types that can be subscribed to.
      x-release-status: PUBLIC
      security:
        - oauth2: []
      parameters:
        - name: api_version
          description: >-
            The API version for which to list event types. Setting this field
            overrides the default version used by the application.
          schema:
            type: string
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWebhookEventTypesResponse'
  /v2/webhooks/subscriptions:
    get:
      tags:
        - WebhookSubscriptions
      summary: ListWebhookSubscriptions
      operationId: ListWebhookSubscriptions
      description: Lists all webhook subscriptions owned by your application.
      x-release-status: PUBLIC
      security:
        - oauth2: []
      parameters:
        - name: cursor
          description: >-
            A pagination cursor returned by a previous call to this endpoint.

            Provide this to retrieve the next set of results for your original
            query.


            For more information, see
            [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).
          schema:
            type: string
          in: query
          required: false
        - name: include_disabled
          description: >-
            Includes disabled [Subscription](entity:WebhookSubscription)s.

            By default, all enabled [Subscription](entity:WebhookSubscription)s
            are returned.
          schema:
            type: boolean
            default: false
          in: query
          required: false
        - name: sort_order
          description: >-
            Sorts the returned list by when the
            [Subscription](entity:WebhookSubscription) was created with the
            specified order.

            This field defaults to ASC.
          schema:
            $ref: '#/components/schemas/SortOrder'
          in: query
          required: false
        - name: limit
          description: >-
            The maximum number of results to be returned in a single page.

            It is possible to receive fewer results than the specified limit on
            a given page.

            The default value of 100 is also the maximum allowed value.


            Default: 100
          schema:
            type: integer
          in: query
          required: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWebhookSubscriptionsResponse'
    post:
      tags:
        - WebhookSubscriptions
      summary: CreateWebhookSubscription
      operationId: CreateWebhookSubscription
      description: Creates a webhook subscription.
      x-release-status: PUBLIC
      security:
        - oauth2: []
      parameters: []
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookSubscriptionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWebhookSubscriptionResponse'
  /v2/webhooks/subscriptions/{subscription_id}:
    delete:
      tags:
        - WebhookSubscriptions
      summary: DeleteWebhookSubscription
      operationId: DeleteWebhookSubscription
      description: Deletes a webhook subscription.
      x-release-status: PUBLIC
      security:
        - oauth2: []
      parameters:
        - name: subscription_id
          description: >-
            [REQUIRED] The ID of the [Subscription](entity:WebhookSubscription)
            to delete.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteWebhookSubscriptionResponse'
    get:
      tags:
        - WebhookSubscriptions
      summary: RetrieveWebhookSubscription
      operationId: RetrieveWebhookSubscription
      description: Retrieves a webhook subscription identified by its ID.
      x-release-status: PUBLIC
      security:
        - oauth2: []
      parameters:
        - name: subscription_id
          description: >-
            [REQUIRED] The ID of the [Subscription](entity:WebhookSubscription)
            to retrieve.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveWebhookSubscriptionResponse'
    put:
      tags:
        - WebhookSubscriptions
      summary: UpdateWebhookSubscription
      operationId: UpdateWebhookSubscription
      description: Updates a webhook subscription.
      x-release-status: PUBLIC
      security:
        - oauth2: []
      parameters:
        - name: subscription_id
          description: >-
            [REQUIRED] The ID of the [Subscription](entity:WebhookSubscription)
            to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookSubscriptionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateWebhookSubscriptionResponse'
  /v2/webhooks/subscriptions/{subscription_id}/signature-key:
    post:
      tags:
        - WebhookSubscriptions
      summary: UpdateWebhookSubscriptionSignatureKey
      operationId: UpdateWebhookSubscriptionSignatureKey
      description: >-
        Updates a webhook subscription by replacing the existing signature key
        with a new one.
      x-release-status: PUBLIC
      security:
        - oauth2: []
      parameters:
        - name: subscription_id
          description: >-
            [REQUIRED] The ID of the [Subscription](entity:WebhookSubscription)
            to update.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/UpdateWebhookSubscriptionSignatureKeyRequest
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/UpdateWebhookSubscriptionSignatureKeyResponse
  /v2/webhooks/subscriptions/{subscription_id}/test:
    post:
      tags:
        - WebhookSubscriptions
      summary: TestWebhookSubscription
      operationId: TestWebhookSubscription
      description: >-
        Tests a webhook subscription by sending a test event to the notification
        URL.
      x-release-status: PUBLIC
      security:
        - oauth2: []
      parameters:
        - name: subscription_id
          description: >-
            [REQUIRED] The ID of the [Subscription](entity:WebhookSubscription)
            to test.
          schema:
            type: string
          in: path
          required: true
      requestBody:
        required: true
        description: |-
          An object containing the fields to POST for the request.

          See the corresponding object definition for field details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestWebhookSubscriptionRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestWebhookSubscriptionResponse'
x-fern-global-headers:
  - header: Square-Version
    name: version
    optional: true
    env: VERSION
    type: literal<"2025-01-23">
