action squareup_search_loyalty_accounts {
  label: "SearchLoyaltyAccounts"
  description: "Searches for loyalty accounts in a loyalty program.  \n\nYou 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.  \n\nSearch results are sorted by `created_at` in ascending order."
  provider: squareup
  method: POST
  path: "/v2/loyalty/accounts/search"
  encoding: json
  input: {
    type: "object"
    description: "A request to search for loyalty accounts."
    properties: {
      cursor: {
        type: "string"
        description: "A pagination cursor returned by a previous call to \nthis endpoint. Provide this to retrieve the next set of \nresults for the original query.\n\nFor more information, \nsee [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)."
      }
      limit: {
        type: "integer"
        description: "The maximum number of results to include in the response."
      }
      query: {
        type: "object"
        description: "The search criteria for the loyalty accounts."
        properties: {
          customer_ids: {
            type: "array"
            description: "The set of customer IDs to use in the loyalty account search.  \n\nThis cannot be combined with `mappings`.  \n\nMax: 30 customer IDs"
            items: {
              type: "string"
            }
          }
          mappings: {
            type: "array"
            description: "The set of mappings to use in the loyalty account search.  \n\nThis cannot be combined with `customer_ids`.  \n\nMax: 30 mappings"
            items: {
              type: "object"
              description: "Represents the mapping that associates a loyalty account with a buyer. \n\nCurrently, a loyalty account can only be mapped to a buyer by phone number. For more information, see \n[Loyalty Overview](https://developer.squareup.com/docs/loyalty/overview)."
              properties: {
                created_at: {
                  type: "string"
                  description: "The timestamp when the mapping was created, in RFC 3339 format."
                }
                id: {
                  type: "string"
                  description: "The Square-assigned ID of the mapping."
                }
                phone_number: {
                  type: "string"
                  description: "The phone number of the buyer, in E.164 format. For example, \"+14155551111\"."
                }
              }
            }
          }
        }
      }
    }
  }
  output: {
    type: "object"
    description: "A response that includes loyalty accounts that satisfy the search criteria."
    properties: {
      cursor: {
        type: "string"
        description: "The pagination cursor to use in a subsequent \nrequest. If empty, this is the final response.\nFor more information, \nsee [Pagination](https://developer.squareup.com/docs/basics/api101/pagination)."
      }
      errors: {
        type: "array"
        description: "Any errors that occurred during the request."
        items: {
          type: "object"
          description: "Represents an error encountered during a request to the Connect API.\n\nSee [Handling errors](https://developer.squareup.com/docs/build-basics/handling-errors) for more information."
          required: ["category", "code"]
          properties: {
            category: {
              type: "string"
              description: "The high-level category for the error."
            }
            code: {
              type: "string"
              description: "The specific code of the error."
            }
            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\nthe error pertains to."
            }
          }
        }
      }
      loyalty_accounts: {
        type: "array"
        description: "The loyalty accounts that met the search criteria,  \nin order of creation date."
        items: {
          type: "object"
          description: "Describes a loyalty account. For more information, see\n[Manage Loyalty Accounts Using the Loyalty API](https://developer.squareup.com/docs/loyalty-api/overview)."
          required: ["program_id"]
          properties: {
            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.\n\nYour 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."
            }
            created_at: {
              type: "string"
              description: "The timestamp when the loyalty account was created, in RFC 3339 format."
            }
            customer_id: {
              type: "string"
              description: "The Square-assigned ID of the [customer](https://developer.squareup.com/reference/square_2021-08-18/objects/Customer) that is associated with the account."
            }
            enrolled_at: {
              type: "string"
              description: "The timestamp when enrollment occurred, in RFC 3339 format."
            }
            expiring_point_deadlines: {
              type: "array"
              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. \n\nThe total number of points in this field equals the number of points in the `balance` field."
              items: {
                type: "object"
                description: "Represents a set of points for a loyalty account that are scheduled to expire on a specific date."
                required: ["points", "expires_at"]
                properties: {
                  expires_at: {
                    type: "string"
                    description: "The timestamp of when the points are scheduled to expire, in RFC 3339 format."
                  }
                  points: {
                    type: "integer"
                    description: "The number of points scheduled to expire at the `expires_at` timestamp."
                  }
                }
              }
            }
            id: {
              type: "string"
              description: "The Square-assigned ID of the loyalty account."
            }
            lifetime_points: {
              type: "integer"
              description: "The total points accrued during the lifetime of the account."
            }
            mapping: {
              type: "object"
              description: "Represents the mapping that associates a loyalty account with a buyer. \n\nCurrently, a loyalty account can only be mapped to a buyer by phone number. For more information, see \n[Loyalty Overview](https://developer.squareup.com/docs/loyalty/overview)."
              properties: {
                created_at: {
                  type: "string"
                  description: "The timestamp when the mapping was created, in RFC 3339 format."
                }
                id: {
                  type: "string"
                  description: "The Square-assigned ID of the mapping."
                }
                phone_number: {
                  type: "string"
                  description: "The phone number of the buyer, in E.164 format. For example, \"+14155551111\"."
                }
              }
            }
            program_id: {
              type: "string"
              description: "The Square-assigned ID of the [loyalty program](https://developer.squareup.com/reference/square_2021-08-18/objects/LoyaltyProgram) to which the account belongs."
            }
            updated_at: {
              type: "string"
              description: "The timestamp when the loyalty account was last updated, in RFC 3339 format."
            }
          }
        }
      }
    }
  }
}